hyperbrane 0.1.0

package/dist/agent/session/worker/jsonRpc.js

@@ -0,0 +1,102 @@
+/**
+ * JSON-RPC 2.0 over a byte stream, one JSON object per line (the framing codex's app-server uses).
+ * Either end can send requests and notifications; the worker protocol (protocol.ts) is built on it.
+ */
+/** Answer for a line that isn't JSON-RPC at all. */
+const PARSE_ERROR = -32700;
+export function createJsonRpcPeer(write, options) {
+    const pending = new Map();
+    let nextId = 1;
+    let buffered = "";
+    let closedWith;
+    function send(message) {
+        if (closedWith)
+            return;
+        write(JSON.stringify({ jsonrpc: "2.0", ...message }) + "\n");
+    }
+    function handle(message) {
+        if (message.method === undefined) {
+            if (message.id === undefined || message.id === null)
+                return;
+            const waiting = pending.get(message.id);
+            pending.delete(message.id);
+            if (message.error)
+                waiting?.reject(options.decodeError(message.error));
+            else
+                waiting?.resolve(message.result);
+            return;
+        }
+        if (message.id === undefined || message.id === null) {
+            options.onNotification?.(message.method, message.params);
+            return;
+        }
+        const id = message.id;
+        options.onRequest(message.method, message.params).then((result) => send({ id, result: result ?? null }), (error) => send({ id, error: options.encodeError(error) }));
+    }
+    function receive(text) {
+        buffered += text;
+        let newline;
+        while ((newline = buffered.indexOf("\n")) >= 0) {
+            const line = buffered.slice(0, newline).trim();
+            buffered = buffered.slice(newline + 1);
+            if (!line)
+                continue;
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                send({ id: null, error: { code: PARSE_ERROR, message: "not JSON" } });
+                continue;
+            }
+            handle(message);
+        }
+    }
+    function request(method, params) {
+        if (closedWith)
+            return Promise.reject(closedWith);
+        const id = nextId++;
+        return new Promise((resolve, reject) => {
+            pending.set(id, { resolve, reject });
+            send({ id, method, params });
+        });
+    }
+    function notify(method, params) {
+        send({ method, params });
+    }
+    function close(error) {
+        closedWith ??= error;
+        for (const waiting of pending.values())
+            waiting.reject(error);
+        pending.clear();
+    }
+    return { receive, request, notify, close };
+}
+/**
+ * Writes to a Bun socket without losing what it can't take yet: the rest is kept and written on
+ * `drain`, which the socket's drain handler must call.
+ */
+export function createSocketWriter(socket) {
+    const encoder = new TextEncoder();
+    let backlog = null;
+    function write(text) {
+        const bytes = encoder.encode(text);
+        if (backlog) {
+            const joined = new Uint8Array(backlog.length + bytes.length);
+            joined.set(backlog);
+            joined.set(bytes, backlog.length);
+            backlog = joined;
+            return;
+        }
+        const written = Math.max(socket.write(bytes), 0);
+        if (written < bytes.length)
+            backlog = bytes.subarray(written);
+    }
+    function drain() {
+        if (!backlog)
+            return;
+        const written = Math.max(socket.write(backlog), 0);
+        backlog = written < backlog.length ? backlog.subarray(written) : null;
+    }
+    return { write, drain };
+}

package/dist/agent/session/worker/protocol.d.ts

@@ -0,0 +1,120 @@
+import { type AgentAuthStatus, type AgentBackend, type AgentBackgroundTask, type AgentLastUserMessage, type AgentModelInfo, type AgentPermissionRequest, type AgentPermissionResult, type AgentQuestionRequest, type AgentQuestionResponse, type AgentSession, type AgentSessionInfo, type AgentSessionLimits, type AgentSessionState, type AgentStreamingMessage, type AgentTranscriptPage, type UserMessage } from "../../api.ts";
+import type { JsonRpcErrorObject } from "./jsonRpc.ts";
+/**
+ * The worker's JSON-RPC protocol, spoken over its unix socket (see createWorkerServer): method ->
+ * [params, result]. Sessions are named by `session`; everything answers `null` unless it says.
+ * worker/health and worker/shutdown are how the host tells a worker's build and replaces it: they
+ * never change.
+ */
+export type WorkerRequests = {
+    "worker/health": [Record<string, never>, WorkerHealth];
+    /** Answers, then stops the sessions' CLIs and exits. */
+    "worker/shutdown": [Record<string, never>, null];
+    "backend/install": [{
+        backend: AgentBackend;
+    }, null];
+    "session/create": [{
+        session: AgentSession;
+    }, AgentSessionInfo];
+    "session/list": [Record<string, never>, AgentSessionInfo[]];
+    "session/update": [{
+        session: string;
+        limits: AgentSessionLimits;
+    }, AgentSessionInfo];
+    "session/stop": [{
+        session: string;
+    }, null];
+    "session/send": [{
+        session: string;
+        message: UserMessage;
+    }, null];
+    "session/interrupt": [{
+        session: string;
+    }, null];
+    "session/status": [{
+        session: string;
+    }, AgentSessionState];
+    "session/lastUserMessages": [{
+        session: string;
+    }, AgentLastUserMessage[]];
+    /**
+     * Streams the session's messages as `session/message` notifications carrying `subscription` (the
+     * client's own id for the stream): first the complete messages after `after_id` (all of them when
+     * omitted) from the backend's transcript, then each message as it comes, until session/unsubscribe
+     * or the connection closes.
+     */
+    "session/subscribe": [{
+        session: string;
+        subscription: string;
+        after_id?: string;
+    }, null];
+    "session/unsubscribe": [{
+        subscription: string;
+    }, null];
+    "session/transcript": [{
+        session: string;
+        limit?: number;
+        cursor?: string;
+    }, AgentTranscriptPage];
+    "permission/list": [{
+        session: string;
+    }, AgentPermissionRequest[]];
+    "permission/respond": [{
+        session: string;
+        request: string;
+        result: AgentPermissionResult;
+    }, null];
+    "question/list": [{
+        session: string;
+    }, AgentQuestionRequest[]];
+    "question/respond": [{
+        session: string;
+        request: string;
+        response: AgentQuestionResponse;
+    }, null];
+    /** Starts the session's CLI if it isn't running. */
+    "model/list": [{
+        session: string;
+    }, AgentModelInfo[]];
+    "model/set": [{
+        session: string;
+        model: string | null;
+    }, null];
+    /** Doesn't start the CLI: a session whose CLI isn't running has no tasks. */
+    "task/list": [{
+        session: string;
+    }, AgentBackgroundTask[]];
+    "task/stop": [{
+        session: string;
+        task: string;
+    }, null];
+    "auth/status": [{
+        session: string;
+    }, AgentAuthStatus];
+    /** `gatewaySignedIn`: the dimension's gateway holds the backend's upstream credential (the host knows; the worker can't). */
+    "auth/login": [{
+        session: string;
+        gatewaySignedIn: boolean;
+    }, AgentAuthStatus];
+    "auth/code": [{
+        session: string;
+        code: string;
+    }, AgentAuthStatus];
+};
+export type WorkerMethod = keyof WorkerRequests;
+export type WorkerNotifications = {
+    "session/message": {
+        subscription: string;
+        message: AgentStreamingMessage;
+    };
+};
+export type WorkerHealth = {
+    agentName: string;
+    build: string;
+};
+export declare class WorkerMethodNotFoundError extends Error {
+    name: string;
+}
+/** The Agent*Errors travel as their own codes, so the client can raise the same class again. */
+export declare function encodeWorkerError(error: unknown): JsonRpcErrorObject;
+export declare function decodeWorkerError({ code, message }: JsonRpcErrorObject): Error;

package/dist/agent/session/worker/protocol.js

@@ -0,0 +1,32 @@
+import { AgentConflictError, AgentInvalidError, AgentNotFoundError, } from "../../api.js";
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const INTERNAL_ERROR = -32603;
+// Server-defined codes, for the Agent*Errors that aren't bad params.
+const NOT_FOUND = -32004;
+const CONFLICT = -32009;
+export class WorkerMethodNotFoundError extends Error {
+    name = "WorkerMethodNotFoundError";
+}
+/** The Agent*Errors travel as their own codes, so the client can raise the same class again. */
+export function encodeWorkerError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof AgentInvalidError)
+        return { code: INVALID_PARAMS, message };
+    if (error instanceof AgentNotFoundError)
+        return { code: NOT_FOUND, message };
+    if (error instanceof AgentConflictError)
+        return { code: CONFLICT, message };
+    if (error instanceof WorkerMethodNotFoundError)
+        return { code: METHOD_NOT_FOUND, message };
+    return { code: INTERNAL_ERROR, message };
+}
+export function decodeWorkerError({ code, message }) {
+    if (code === INVALID_PARAMS)
+        return new AgentInvalidError(message);
+    if (code === NOT_FOUND)
+        return new AgentNotFoundError(message);
+    if (code === CONFLICT)
+        return new AgentConflictError(message);
+    return new Error(`worker: ${message}`);
+}

package/dist/agent/session/workerConnection.d.ts

@@ -0,0 +1,29 @@
+import type { Sandbox } from "../../sandbox/api.ts";
+import { type WorkerMethod, type WorkerNotifications, type WorkerRequests } from "./worker/protocol.ts";
+/** One connection to a worker: typed requests, and the notifications it pushes. */
+export type WorkerConnection = {
+    request<M extends WorkerMethod>(method: M, params: WorkerRequests[M][0]): Promise<WorkerRequests[M][1]>;
+    /** Resolves when the worker closes the connection (or it fails). */
+    closed: Promise<void>;
+    close(): void;
+};
+export type WorkerNotificationHandler = <N extends keyof WorkerNotifications>(method: N, params: WorkerNotifications[N]) => void;
+/** Opens a connection; notifications go to `onNotification`. */
+export type ConnectWorker = (onNotification?: WorkerNotificationHandler) => Promise<WorkerConnection>;
+/** A text stream to a worker that its JSON-RPC lines go out and come in on. */
+export type WorkerTransport = {
+    write(text: string): void;
+    /** Receives the text read from the worker, in order. Registered before anything arrives. */
+    onText(listener: (text: string) => void): void;
+    /** Resolves once the transport is closed, by either side or by an error. */
+    closed: Promise<void>;
+    close(): void;
+};
+/** A connection speaking JSON-RPC over `transport` (`label` says where to, in errors). */
+export declare function workerConnectionOver(transport: WorkerTransport, label: string, onNotification?: WorkerNotificationHandler): WorkerConnection;
+/**
+ * Connects over the worker's unix socket at `socketPath` in `host` (the dimension's run directory is
+ * mounted on the host, wherever that is: this machine, or a server reached over SSH), speaking
+ * JSON-RPC.
+ */
+export declare function workerSocketConnector(host: Sandbox, socketPath: string): ConnectWorker;

package/dist/agent/session/workerConnection.js

@@ -0,0 +1,44 @@
+import { createJsonRpcPeer } from "./worker/jsonRpc.js";
+import { WorkerMethodNotFoundError, decodeWorkerError, encodeWorkerError, } from "./worker/protocol.js";
+/** A connection speaking JSON-RPC over `transport` (`label` says where to, in errors). */
+export function workerConnectionOver(transport, label, onNotification) {
+    let peer;
+    transport.onText((text) => peer?.receive(text));
+    const closed = transport.closed.then(() => peer?.close(new Error(`the worker at ${label} closed the connection`)));
+    peer = createJsonRpcPeer((text) => transport.write(text), {
+        // The worker makes no requests of its clients.
+        onRequest: async (method) => {
+            throw new WorkerMethodNotFoundError(`no method ${method}`);
+        },
+        // type-bypass: notifications arrive as JSON; the worker only sends those in WorkerNotifications.
+        onNotification: (method, params) => onNotification?.(method, params),
+        encodeError: encodeWorkerError,
+        decodeError: decodeWorkerError,
+    });
+    const connected = peer;
+    return {
+        // type-bypass: the result is the one WorkerRequests pairs with this method.
+        request: (method, params) => connected.request(method, params),
+        closed,
+        close: () => transport.close(),
+    };
+}
+/**
+ * Connects over the worker's unix socket at `socketPath` in `host` (the dimension's run directory is
+ * mounted on the host, wherever that is: this machine, or a server reached over SSH), speaking
+ * JSON-RPC.
+ */
+export function workerSocketConnector(host, socketPath) {
+    return async (onNotification) => {
+        const decoder = new TextDecoder();
+        const encoder = new TextEncoder();
+        const socket = await host.connect(socketPath);
+        const transport = {
+            write: (text) => socket.write(encoder.encode(text)),
+            onText: (listener) => socket.onData((data) => listener(decoder.decode(data, { stream: true }))),
+            closed: socket.closed,
+            close: () => socket.close(),
+        };
+        return workerConnectionOver(transport, socketPath, onNotification);
+    };
+}

package/dist/agent/session/workerSseConnection.d.ts

@@ -0,0 +1,15 @@
+import type { SandboxEndpoint } from "../../sandbox/api.ts";
+import { type ConnectWorker } from "./workerConnection.ts";
+export { EndpointLoginRequiredError, exeDevLoginUrl, sseEvents } from "../../sandbox/sseConnection.ts";
+/** Where a worker is reached, and how (AgentService.exposeAgent's answer). */
+export type WorkerEndpoint = Pick<SandboxEndpoint, "url" | "credentials">;
+/**
+ * Connects to a worker through its accessible endpoint (AgentService.exposeAgent: the endpoint
+ * proxy's "sse" transport), each connection an openSseConnection. Given a function, it asks it for
+ * the endpoint before every connection, so a proxy that stopped is started again (exposeAgent does
+ * that) before the client needs it. Runs in a browser as well as on a server. Aborting `signal`
+ * closes every connection it opened (a stream waiting for the next message included).
+ */
+export declare function workerSseConnector(endpoint: WorkerEndpoint | (() => Promise<WorkerEndpoint>), { signal }?: {
+    signal?: AbortSignal;
+}): ConnectWorker;

package/dist/agent/session/workerSseConnection.js

@@ -0,0 +1,26 @@
+import { openSseConnection } from "../../sandbox/sseConnection.js";
+import { workerConnectionOver } from "./workerConnection.js";
+export { EndpointLoginRequiredError, exeDevLoginUrl, sseEvents } from "../../sandbox/sseConnection.js";
+/**
+ * Connects to a worker through its accessible endpoint (AgentService.exposeAgent: the endpoint
+ * proxy's "sse" transport), each connection an openSseConnection. Given a function, it asks it for
+ * the endpoint before every connection, so a proxy that stopped is started again (exposeAgent does
+ * that) before the client needs it. Runs in a browser as well as on a server. Aborting `signal`
+ * closes every connection it opened (a stream waiting for the next message included).
+ */
+export function workerSseConnector(endpoint, { signal } = {}) {
+    return async (onNotification) => {
+        signal?.throwIfAborted();
+        const access = typeof endpoint === "function" ? await endpoint() : endpoint;
+        const connection = await openSseConnection(access, { signal });
+        const decoder = new TextDecoder();
+        const encoder = new TextEncoder();
+        const transport = {
+            write: (text) => connection.write(encoder.encode(text)),
+            onText: (listener) => connection.onData((data) => listener(decoder.decode(data, { stream: true }))),
+            closed: connection.closed,
+            close: () => connection.close(),
+        };
+        return workerConnectionOver(transport, access.url.replace(/\/+$/, ""), onNotification);
+    };
+}

package/dist/agent/workerBundle.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The session worker (agent/session/main.ts and all it imports) as the one script AgentService
+ * uploads into a dimension and runs with bun. The backends' own packages aren't part of it: the
+ * worker installs them into the dimension and loads them from there.
+ */
+export type WorkerBundle = {
+    /** The worker as one script for bun. */
+    source: string;
+    /** Identifies the source: a running worker with another build is replaced. */
+    build: string;
+};
+/**
+ * The worker, once per process. Under Bun with the sources at hand (a checkout) it is bundled from
+ * them; otherwise (Node, or the built package, which ships no sources) it comes from
+ * agent/workerBundle.generated.ts (scripts/bundle-worker.ts).
+ */
+export declare function workerBundle(): Promise<WorkerBundle>;
+/** Bundles the worker with Bun.build. */
+export declare function buildWorkerSource(): Promise<string>;

package/dist/agent/workerBundle.generated.d.ts

@@ -0,0 +1 @@
+export declare const WORKER_SOURCE: string;