hyperbrane 0.1.0

package/dist/agent/api.d.ts

@@ -0,0 +1,264 @@
+import type { ModelInfo, SDKBackgroundTasksChangedMessage, PermissionResult, SDKAssistantMessage, SDKPartialAssistantMessage, SDKResultMessage, SDKSystemMessage, SDKUserMessage } from "../vendor-types/claude/agent-sdk/sdk.js";
+import type { AskUserQuestionInput } from "../vendor-types/claude/agent-sdk/sdk-tools.js";
+import type { CPULimit, MemoryLimit } from "../dimension/api.ts";
+import type { SandboxEndpoint, SandboxEndpointScheme } from "../sandbox/api.ts";
+/** A session worker running in a dimension; it hosts that agent's sessions. */
+export type Agent = {
+    name: string;
+    dimensionName: string;
+};
+/** The agent CLIs a session can run (agent/session/<backend>/). */
+export declare const AGENT_BACKENDS: readonly ["claude", "codex"];
+export type AgentBackend = (typeof AGENT_BACKENDS)[number];
+export type AgentSession = {
+    name: string;
+    backend: AgentBackend;
+    memoryLimit: MemoryLimit;
+    cpuLimit: CPULimit;
+    /** Dimension path the agent works in; defaults to the workspace. */
+    cwd?: string;
+    /** Extra environment for the agent CLI (e.g. ANTHROPIC_BASE_URL). */
+    env?: Record<string, string>;
+};
+/** What `updateSession` can change; omitted limits stay as they are. */
+export type AgentSessionLimits = Partial<Pick<AgentSession, "memoryLimit" | "cpuLimit">>;
+/**
+ * Where a session's CLI stands, as the CLI itself reports it (claude's session state, codex's thread
+ * status). "stopped": no CLI running (none started yet, or it exited; the next message starts one).
+ * "waiting": a turn is blocked on a permission request or a question. "error": the CLI says it can't
+ * go on (codex's systemError).
+ */
+export type AgentSessionState = "stopped" | "starting" | "idle" | "running" | "waiting" | "error";
+export type AgentSessionInfo = AgentSession & {
+    agentName: string;
+    status: AgentSessionState;
+    /** The backend's own id for the conversation (claude's session id, codex's thread id), once known. */
+    nativeId: string | null;
+    /** Chosen through AgentModels; null for the backend's default. */
+    model: string | null;
+};
+/** Where a session lives: sessions are named per agent. */
+export type SessionRef = {
+    agentName: string;
+    sessionName: string;
+};
+export interface AgentClient {
+    /** PUT /v1/agents/:agentName — starts (or updates) the worker in the dimension. */
+    createAgent(agent: Agent): Promise<Agent>;
+    /** DELETE /v1/agents/:agentName — stops the worker and its sessions. */
+    stopAgent(agentName: string): Promise<void>;
+    /** GET /v1/agents */
+    listAgents(): Promise<Agent[]>;
+    /** POST /v1/agents/:agentName/sessions — idempotent for the same spec. */
+    createSession(agentName: string, session: AgentSession): Promise<AgentSessionInfo>;
+    /** PATCH /v1/agents/:agentName/sessions/:sessionName — changes its limits. */
+    updateSession(ref: SessionRef, limits: AgentSessionLimits): Promise<AgentSessionInfo>;
+    /** GET /v1/sessions — every agent's sessions. */
+    listSessions(): Promise<AgentSessionInfo[]>;
+    /** DELETE /v1/agents/:agentName/sessions/:sessionName — ends the CLI and forgets the session. */
+    stopSession(ref: SessionRef): Promise<void>;
+}
+export type AgentStreamingRequest = {
+    /**
+     * The `uuid` of the last user or assistant message already seen (e.g. the prompt just sent);
+     * omitted to read the whole conversation. Those uuids are the backend's own ids for the messages
+     * it stores, so a stream resumes from the backend's transcript; partial output and results aren't
+     * stored and can't be resumed from.
+     */
+    after_id?: string;
+};
+/**
+ * The SDK messages a session streams. `stream_event` messages are the partial assistant output;
+ * `assistant`/`user` the complete messages (tool calls and their results included), each with the
+ * uuid its backend stores it under; `result` ends each turn. codex sessions emit no `system` message.
+ */
+export type AgentStreamingMessage = SDKSystemMessage | SDKAssistantMessage | SDKPartialAssistantMessage | (SDKUserMessage & {
+    uuid: string;
+    session_id: string;
+}) | SDKResultMessage;
+/** A complete message of the conversation so far (no partial output), as the stream carried it. */
+export type AgentTranscriptMessage = Extract<AgentStreamingMessage, {
+    type: "user" | "assistant";
+}>;
+export type AgentTranscriptRequest = {
+    /** How many messages a page holds, about (a tool call and its result share a page); default 50, at most 500. */
+    limit?: number;
+    /** A page's `nextCursor`, for the page before it; omitted for the newest page. */
+    cursor?: string;
+};
+/** Newest pages first; each page's messages oldest first. */
+export type AgentTranscriptPage = {
+    messages: AgentTranscriptMessage[];
+    nextCursor: string | null;
+};
+export type UserMessage = SDKUserMessage;
+/**
+ * A tool call waiting for permission: claude's canUseTool call. The SDK's own permission request (its
+ * `can_use_tool` control request) isn't exported, so this mirrors it.
+ */
+export type AgentPermissionRequest = {
+    id: string;
+    tool_name: string;
+    input: Record<string, unknown>;
+    tool_use_id: string;
+    /** Why the agent asks, when it says (e.g. codex's reason for wanting network access). */
+    decision_reason?: string;
+};
+export type AgentPermissionResult = PermissionResult;
+type AskUserQuestion = AskUserQuestionInput["questions"][number];
+/** A question of claude's AskUserQuestion tool; codex's may come with any number of options. */
+export type AgentQuestion = Omit<AskUserQuestion, "options"> & {
+    options: AskUserQuestion["options"][number][];
+};
+/** The agent asking the user something (claude's AskUserQuestion, codex's request_user_input). */
+export type AgentQuestionRequest = {
+    id: string;
+    tool_use_id: string;
+    questions: AgentQuestion[];
+};
+/**
+ * AskUserQuestion's own answer: question text -> the chosen label (labels joined with ", " for a
+ * multi-select), or the user's own words.
+ */
+export type AgentQuestionResponse = {
+    answers: NonNullable<AskUserQuestionInput["answers"]>;
+};
+/** One of the models a session can be switched to. */
+export type AgentModelInfo = ModelInfo;
+/**
+ * A task the agent keeps running after the tool call that started it has returned: claude's
+ * background commands and agents (its own shape, from background_tasks_changed), codex's background
+ * terminals.
+ */
+export type AgentBackgroundTask = SDKBackgroundTasksChangedMessage["tasks"][number];
+/**
+ * Where a session's CLI stands with its sign-in. The CLI signs in as it normally would, through the
+ * dimension's gateway, which keeps the real tokens and gives the CLI fakes. "pending": a sign-in is
+ * waiting for the user to open `url` (and, for codex, enter `userCode` there; for claude, send back
+ * the code the page shows, when `needsCode`).
+ */
+export type AgentAuthStatus = {
+    state: "signedIn";
+} | {
+    state: "signedOut"; /** Why the last sign-in failed, if one did. */
+    error?: string;
+} | {
+    state: "pending";
+    url: string;
+    userCode?: string;
+    needsCode: boolean;
+};
+export interface AgentProvision {
+    /** POST /v1/agents/:agentName/backends/:backend/install — installs the backend in the dimension, or updates it. */
+    install(agentName: string, backend: AgentBackend): Promise<void>;
+}
+export interface AgentEndpoint {
+    /**
+     * POST /v1/agents/:agentName/endpoint — the agent's worker, reachable from the client over the
+     * network (workerSseConnector speaks to it), authenticated by `scheme`, callable from pages of
+     * `allowedOrigins`. Call it before each connection: it starts the endpoint's proxy again if that
+     * stopped, keeping the same URL and credentials; a new endpoint only for another scheme or origins,
+     * or once the old one can't be served (closed, its port taken). Closed with the agent. Needs a host
+     * that declares endpoints.
+     */
+    exposeAgent(agentName: string, scheme: SandboxEndpointScheme, allowedOrigins?: string[]): Promise<SandboxEndpoint>;
+}
+export interface AgentStream {
+    /**
+     * GET /v1/agents/:agentName/sessions/:sessionName/stream?after_id= — the complete messages after
+     * `after_id` from the backend's transcript, then each message as the session produces it, pushed
+     * by the worker (session/subscribe) until the caller stops reading. Throws if the worker goes
+     * away; resume with the last user or assistant uuid seen.
+     */
+    getStream(ref: SessionRef, req: AgentStreamingRequest): AsyncGenerator<AgentStreamingMessage>;
+}
+export interface AgentTranscript {
+    /**
+     * GET /v1/agents/:agentName/sessions/:sessionName/transcript?limit=&cursor= — a page of the
+     * conversation, read from the backend's own storage a piece at a time, so a conversation of any
+     * length can be paged through.
+     */
+    getTranscript(ref: SessionRef, req?: AgentTranscriptRequest): Promise<AgentTranscriptPage>;
+}
+export interface AgentInterrupt {
+    /** POST /v1/agents/:agentName/sessions/:sessionName/interrupt — ends the current turn; pending permission requests are denied and questions dropped. */
+    cancel(ref: SessionRef): Promise<void>;
+}
+export interface AgentInput {
+    /**
+     * POST /v1/agents/:agentName/sessions/:sessionName/messages — resolves once the agent confirms it
+     * received the message (it starts a turn, or waits in the agent's own queue); fails if the agent
+     * refuses it or doesn't confirm.
+     */
+    sendMessage(ref: SessionRef, message: UserMessage): Promise<void>;
+}
+export interface AgentSessionStatus {
+    /** GET /v1/agents/:agentName/sessions/:sessionName/status */
+    getSessionStatus(ref: SessionRef): Promise<AgentSessionState>;
+}
+export interface AgentMessageQueue {
+    /**
+     * GET /v1/agents/:agentName/sessions/:sessionName/queue — from the agent (claude's command
+     * lifecycle, codex's turn items), oldest first: the last message it took into a turn, then every
+     * one it still holds queued. While no CLI runs (nothing can be queued), the last prompt in its
+     * transcript. Empty before the first message.
+     */
+    getLastUserMessages(ref: SessionRef): Promise<AgentLastUserMessage[]>;
+}
+export interface AgentPermissions {
+    /** GET /v1/agents/:agentName/sessions/:sessionName/permission-requests — the ones still waiting. */
+    listPermissionRequests(ref: SessionRef): Promise<AgentPermissionRequest[]>;
+    /** POST /v1/agents/:agentName/sessions/:sessionName/permission-requests/:requestId */
+    respondPermissionRequest(ref: SessionRef, requestId: string, result: AgentPermissionResult): Promise<void>;
+}
+export interface AgentQuestions {
+    /** GET /v1/agents/:agentName/sessions/:sessionName/question-requests — the ones still waiting. */
+    listQuestionRequests(ref: SessionRef): Promise<AgentQuestionRequest[]>;
+    /** POST /v1/agents/:agentName/sessions/:sessionName/question-requests/:requestId */
+    respondQuestionRequest(ref: SessionRef, requestId: string, response: AgentQuestionResponse): Promise<void>;
+}
+export interface AgentBackgroundTasks {
+    /** GET /v1/agents/:agentName/sessions/:sessionName/background-tasks — those still running; none while the CLI isn't. */
+    listBackgroundTasks(ref: SessionRef): Promise<AgentBackgroundTask[]>;
+    /** POST /v1/agents/:agentName/sessions/:sessionName/background-tasks/:taskId/stop — ends the task. */
+    stopTask(ref: SessionRef, taskId: string): Promise<void>;
+}
+export interface AgentAuth {
+    /** GET /v1/agents/:agentName/sessions/:sessionName/auth */
+    getAuthStatus(ref: SessionRef): Promise<AgentAuthStatus>;
+    /**
+     * POST /v1/agents/:agentName/sessions/:sessionName/auth/login — signs the session's CLI in with
+     * its own login. When the dimension's gateway already holds the upstream's credential, the sign-in
+     * completes without anyone (the gateway answers it) and this resolves signed in; otherwise it
+     * resolves pending, with the link for the user, and the gateway keeps the tokens once they sign in.
+     */
+    login(ref: SessionRef): Promise<AgentAuthStatus>;
+    /** POST /v1/agents/:agentName/sessions/:sessionName/auth/code — finishes a pending sign-in that needs the page's code. */
+    submitAuthCode(ref: SessionRef, code: string): Promise<AgentAuthStatus>;
+}
+export interface AgentModels {
+    /** GET /v1/agents/:agentName/sessions/:sessionName/models — starts the CLI if it isn't running. */
+    listModels(ref: SessionRef): Promise<AgentModelInfo[]>;
+    /** PUT /v1/agents/:agentName/sessions/:sessionName/model — from the next turn on; null for the backend's default. */
+    setModel(ref: SessionRef, model: string | null): Promise<void>;
+}
+/** Everything a session can do, each call naming the session. */
+export type AgentSessionCapabilities = AgentStream & AgentTranscript & AgentInterrupt & AgentInput & AgentSessionStatus & AgentMessageQueue & AgentPermissions & AgentQuestions & AgentBackgroundTasks & AgentAuth & AgentModels;
+/** A message sent to a session, and whether its agent still holds it queued (not yet taken into a turn). */
+export type AgentLastUserMessage = {
+    message: UserMessage;
+    queued: boolean;
+};
+/** The request can't be satisfied as sent (bad name, unknown backend, unknown after_id, ...). */
+export declare class AgentInvalidError extends Error {
+    name: string;
+}
+/** No agent, session, permission or question request by that name. */
+export declare class AgentNotFoundError extends Error {
+    name: string;
+}
+/** The name is taken with a different spec. */
+export declare class AgentConflictError extends Error {
+    name: string;
+}
+export {};

package/dist/agent/api.js

@@ -0,0 +1,14 @@
+/** The agent CLIs a session can run (agent/session/<backend>/). */
+export const AGENT_BACKENDS = ["claude", "codex"];
+/** The request can't be satisfied as sent (bad name, unknown backend, unknown after_id, ...). */
+export class AgentInvalidError extends Error {
+    name = "AgentInvalidError";
+}
+/** No agent, session, permission or question request by that name. */
+export class AgentNotFoundError extends Error {
+    name = "AgentNotFoundError";
+}
+/** The name is taken with a different spec. */
+export class AgentConflictError extends Error {
+    name = "AgentConflictError";
+}

package/dist/agent/gatewaySignIns.d.ts

@@ -0,0 +1,5 @@
+import type { GatewayService } from "../portal-gateway/gatewayService.ts";
+import type { PortalService } from "../portal-gateway/portalService.ts";
+/** Whether a gateway behind the dimension's portals holds an OAuth sign-in for the upstream. */
+export type GatewaySignIns = (dimensionName: string, upstreamName: string) => Promise<boolean>;
+export declare function createGatewaySignIns(portals: PortalService, gateways: GatewayService): GatewaySignIns;

package/dist/agent/gatewaySignIns.js

@@ -0,0 +1,11 @@
+export function createGatewaySignIns(portals, gateways) {
+    return async (dimensionName, upstreamName) => {
+        const gatewayNames = new Set((await portals.listPortals()).filter((portal) => portal.dimensionName === dimensionName).map((portal) => portal.gatewayName));
+        for (const gatewayName of gatewayNames) {
+            const credentials = await gateways.listCredentials(gatewayName);
+            if (credentials.some((credential) => credential.name === `${upstreamName}.oauth`))
+                return true;
+        }
+        return false;
+    };
+}

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

@@ -0,0 +1,14 @@
+import type { AgentStreamingMessage } from "../api.ts";
+import type { WorkerMethod, WorkerRequests } from "./worker/protocol.ts";
+import type { ConnectWorker } from "./workerConnection.ts";
+/** The worker's protocol (protocol.ts). Errors come back as the Agent*Error they were. */
+export type WorkerClient = {
+    call<M extends WorkerMethod>(method: M, params: WorkerRequests[M][0]): Promise<WorkerRequests[M][1]>;
+    /**
+     * The session's messages after `afterId`, then each one as the worker produces it, over a
+     * connection held open while the caller reads. Throws once the worker goes away.
+     */
+    stream(sessionName: string, afterId: string | undefined): AsyncGenerator<AgentStreamingMessage>;
+};
+/** Calls the worker over the connections `connect` opens (workerSocketConnector: its unix socket). */
+export declare function createWorkerClient(connect: ConnectWorker): WorkerClient;

package/dist/agent/session/client.js

@@ -0,0 +1,47 @@
+/** Calls the worker over the connections `connect` opens (workerSocketConnector: its unix socket). */
+export function createWorkerClient(connect) {
+    /** One request on a connection of its own. */
+    async function call(method, params) {
+        const connection = await connect();
+        try {
+            return await connection.request(method, params);
+        }
+        finally {
+            connection.close();
+        }
+    }
+    async function* stream(session, afterId) {
+        const subscription = crypto.randomUUID();
+        const queued = [];
+        let wake;
+        let ended = false;
+        const connection = await connect((method, params) => {
+            if (method !== "session/message" || params.subscription !== subscription)
+                return;
+            queued.push(params.message);
+            wake?.();
+        });
+        connection.closed.then(() => {
+            ended = true;
+            wake?.();
+        });
+        try {
+            await connection.request("session/subscribe", { session, subscription, after_id: afterId });
+            for (;;) {
+                while (queued.length > 0)
+                    yield queued.shift();
+                if (ended)
+                    throw new Error(`the worker closed the stream of session ${session}`);
+                await new Promise((resolve) => (wake = resolve));
+                wake = undefined;
+            }
+        }
+        finally {
+            // On a shared connection (sharedConnector) the worker would go on sending to it otherwise.
+            if (!ended)
+                connection.request("session/unsubscribe", { subscription }).catch(() => { });
+            connection.close();
+        }
+    }
+    return { call, stream };
+}

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

@@ -0,0 +1,66 @@
+import type { Sandbox } from "../../sandbox/api.ts";
+import type { AgentAuthStatus, AgentBackend, AgentPermissionRequest, AgentQuestionRequest, AgentSession } from "../api.ts";
+/** What the worker keeps of a session: never its messages, which are the backend's to store. */
+export type SessionRecord = {
+    spec: AgentSession;
+    /** The backend's id for the conversation, once known: what a new worker resumes. */
+    nativeId: string | null;
+    /** Chosen through AgentModels; null for the backend's default. */
+    model: string | null;
+};
+/** Where a session's CLI stands with its sign-in, as far as it outlives a request. */
+export type SessionAuthRecord = {
+    /** Where the CLI's login in progress asked the user to sign in; null when none is. */
+    login: Extract<AgentAuthStatus, {
+        state: "pending";
+    }> | null;
+    /** Why the last login failed, if it did. */
+    error: string | null;
+};
+/** Every name must pass checkName; operations throw InvalidNameError otherwise. */
+export interface SessionStorage {
+    getSessions(): Promise<SessionRecord[]>;
+    /** Stores the record unless one with that name exists; returns whichever record is stored afterwards. */
+    insertSession(record: SessionRecord): Promise<SessionRecord>;
+    /** Replaces the record. */
+    saveSession(record: SessionRecord): Promise<void>;
+    /** Removes the record and everything kept for the session. No-op if missing. */
+    removeSession(sessionName: string): Promise<void>;
+    /** The permission requests the session's CLI is waiting on, oldest first. */
+    getPermissionRequests(sessionName: string): Promise<AgentPermissionRequest[]>;
+    savePermissionRequest(sessionName: string, request: AgentPermissionRequest): Promise<void>;
+    /** No-op if missing. */
+    removePermissionRequest(sessionName: string, requestId: string): Promise<void>;
+    /** The questions the session's CLI is waiting on, oldest first. */
+    getQuestionRequests(sessionName: string): Promise<AgentQuestionRequest[]>;
+    saveQuestionRequest(sessionName: string, request: AgentQuestionRequest): Promise<void>;
+    /** No-op if missing. */
+    removeQuestionRequest(sessionName: string, requestId: string): Promise<void>;
+    /** Null until the session's CLI has been asked to sign in. */
+    readAuth(sessionName: string): Promise<SessionAuthRecord | null>;
+    saveAuth(sessionName: string, record: SessionAuthRecord): Promise<void>;
+    /** Sandbox path of the unix socket the agent's worker listens on (see workerSocketPath). */
+    socketPath(): Promise<string>;
+    /**
+     * Sandbox path of the backend CLI's home (claude's config directory, codex's CODEX_HOME): its
+     * sign-in, config and conversations, kept with the rest of the dimension's state. Shared by the
+     * dimension's agents, like a home would be. Creates it.
+     */
+    backendHome(backend: AgentBackend): Promise<string>;
+}
+/**
+ * The agent's worker socket in a dimension's run directory: RUN_PATH inside the dimension, or the
+ * host side of that mount, so the host reaches the worker through it.
+ */
+export declare function workerSocketPath(runDirectory: string, agentName: string): string;
+/**
+ * `stateDirectory` is a sandbox path: the dimension's state directory (STATE_PATH, mounted from the
+ * host's hyperbrane storage, so everything here lives there with the rest). Layout:
+ * agents/<agent>/sessions/<session>.json, and agents/<agent>/sessions/<session>/ holding
+ * permission-requests/<id>.json, question-requests/<id>.json and auth.json; backends/<backend>/
+ * (the CLIs' homes). The socket goes in `runDirectory`, the dimension's run directory.
+ */
+export declare function createSessionStorage(sandbox: Sandbox, agentName: string, { stateDirectory, runDirectory }?: {
+    stateDirectory?: string;
+    runDirectory?: string;
+}): SessionStorage;

package/dist/agent/session/sessionStorage.js

@@ -0,0 +1,89 @@
+import { RUN_PATH, STATE_PATH } from "../../dimension/paths.js";
+import { checkName, createJsonDirectory } from "../../lib/jsonDirectory.js";
+/**
+ * The agent's worker socket in a dimension's run directory: RUN_PATH inside the dimension, or the
+ * host side of that mount, so the host reaches the worker through it.
+ */
+export function workerSocketPath(runDirectory, agentName) {
+    return `${runDirectory}/${agentName}.sock`;
+}
+/**
+ * `stateDirectory` is a sandbox path: the dimension's state directory (STATE_PATH, mounted from the
+ * host's hyperbrane storage, so everything here lives there with the rest). Layout:
+ * agents/<agent>/sessions/<session>.json, and agents/<agent>/sessions/<session>/ holding
+ * permission-requests/<id>.json, question-requests/<id>.json and auth.json; backends/<backend>/
+ * (the CLIs' homes). The socket goes in `runDirectory`, the dimension's run directory.
+ */
+export function createSessionStorage(sandbox, agentName, { stateDirectory = STATE_PATH, runDirectory = RUN_PATH } = {}) {
+    const sessionsDir = `${stateDirectory}/agents/${agentName}/sessions`;
+    const sessions = createJsonDirectory(sandbox, async () => sessionsDir);
+    const sessionDir = (sessionName) => `${sessionsDir}/${checkName(sessionName)}`;
+    const permissionRequests = (sessionName) => createJsonDirectory(sandbox, async () => `${sessionDir(sessionName)}/permission-requests`);
+    const questionRequests = (sessionName) => createJsonDirectory(sandbox, async () => `${sessionDir(sessionName)}/question-requests`);
+    const sessionFiles = (sessionName) => createJsonDirectory(sandbox, async () => sessionDir(sessionName));
+    async function oldestFirst(stored) {
+        return (await stored).sort((a, b) => a.at - b.at).map((entry) => entry.request);
+    }
+    async function getSessions() {
+        return sessions.list();
+    }
+    async function insertSession(record) {
+        return sessions.insert(record.spec.name, record);
+    }
+    async function saveSession(record) {
+        await sessions.save(record.spec.name, record);
+    }
+    // Everything kept for it first: while the record is there, the removal can be retried.
+    async function removeSession(sessionName) {
+        await sandbox.removeDirectory(sessionDir(sessionName));
+        await sessions.remove(sessionName);
+    }
+    async function getPermissionRequests(sessionName) {
+        return oldestFirst(permissionRequests(sessionName).list());
+    }
+    async function savePermissionRequest(sessionName, request) {
+        await permissionRequests(sessionName).save(request.id, { request, at: Date.now() });
+    }
+    async function removePermissionRequest(sessionName, requestId) {
+        await permissionRequests(sessionName).remove(requestId);
+    }
+    async function getQuestionRequests(sessionName) {
+        return oldestFirst(questionRequests(sessionName).list());
+    }
+    async function saveQuestionRequest(sessionName, request) {
+        await questionRequests(sessionName).save(request.id, { request, at: Date.now() });
+    }
+    async function removeQuestionRequest(sessionName, requestId) {
+        await questionRequests(sessionName).remove(requestId);
+    }
+    async function readAuth(sessionName) {
+        return sessionFiles(sessionName).read("auth");
+    }
+    async function saveAuth(sessionName, record) {
+        await sessionFiles(sessionName).save("auth", record);
+    }
+    async function socketPath() {
+        return workerSocketPath(runDirectory, agentName);
+    }
+    async function backendHome(backend) {
+        const path = `${stateDirectory}/backends/${backend}`;
+        await sandbox.createDirectory(path);
+        return path;
+    }
+    return {
+        getSessions,
+        insertSession,
+        saveSession,
+        removeSession,
+        getPermissionRequests,
+        savePermissionRequest,
+        removePermissionRequest,
+        getQuestionRequests,
+        saveQuestionRequest,
+        removeQuestionRequest,
+        readAuth,
+        saveAuth,
+        socketPath,
+        backendHome,
+    };
+}

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

@@ -0,0 +1,13 @@
+import type { ConnectWorker } from "./workerConnection.ts";
+export type SharedConnector = ConnectWorker & {
+    /** Closes the connection they share (a later connect opens another). */
+    close(): void;
+};
+/**
+ * One connection to the worker, shared by everyone `connect`s through it: each gets a view of it
+ * (its requests go over it, the worker's notifications reach every view, closing a view only
+ * detaches it), so calls cost a round trip each rather than a connection each. Over an endpoint
+ * that's what matters (workerSseConnector opens an event stream per connection). The connection is
+ * opened on first use, and again after it closes.
+ */
+export declare function sharedConnector(connect: ConnectWorker): SharedConnector;

package/dist/agent/session/sharedConnection.js

@@ -0,0 +1,55 @@
+/**
+ * One connection to the worker, shared by everyone `connect`s through it: each gets a view of it
+ * (its requests go over it, the worker's notifications reach every view, closing a view only
+ * detaches it), so calls cost a round trip each rather than a connection each. Over an endpoint
+ * that's what matters (workerSseConnector opens an event stream per connection). The connection is
+ * opened on first use, and again after it closes.
+ */
+export function sharedConnector(connect) {
+    let current = null;
+    function open() {
+        if (current)
+            return current;
+        const handlers = new Set();
+        const dispatch = (method, params) => {
+            for (const handler of handlers)
+                handler(method, params);
+        };
+        const opening = connect(dispatch).then((connection) => {
+            void connection.closed.then(() => {
+                if (current === opening)
+                    current = null;
+            });
+            return { connection, handlers };
+        });
+        opening.catch(() => {
+            if (current === opening)
+                current = null;
+        });
+        current = opening;
+        return opening;
+    }
+    const shared = (async (onNotification) => {
+        const { connection, handlers } = await open();
+        if (onNotification)
+            handlers.add(onNotification);
+        let detach;
+        const closed = new Promise((resolve) => (detach = resolve));
+        void connection.closed.then(() => detach());
+        return {
+            request: (method, params) => connection.request(method, params),
+            closed,
+            close() {
+                if (onNotification)
+                    handlers.delete(onNotification);
+                detach();
+            },
+        };
+    });
+    shared.close = () => {
+        const closing = current;
+        current = null;
+        void closing?.then(({ connection }) => connection.close(), () => { });
+    };
+    return shared;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+export type JsonRpcId = string | number;
+export type JsonRpcErrorObject = {
+    code: number;
+    message: string;
+    data?: unknown;
+};
+export type JsonRpcPeerOptions = {
+    /** Answers a request; what it throws goes back as an error response, through `encodeError`. */
+    onRequest(method: string, params: unknown): Promise<unknown>;
+    onNotification?(method: string, params: unknown): void;
+    encodeError(error: unknown): JsonRpcErrorObject;
+    decodeError(error: JsonRpcErrorObject): Error;
+};
+export interface JsonRpcPeer {
+    /** Feeds text read from the connection; complete lines are handled as they arrive. */
+    receive(text: string): void;
+    request(method: string, params: unknown): Promise<unknown>;
+    notify(method: string, params: unknown): void;
+    /** Fails every request still waiting for its response. */
+    close(error: Error): void;
+}
+export declare function createJsonRpcPeer(write: (line: string) => void, options: JsonRpcPeerOptions): JsonRpcPeer;
+/** The part of a Bun socket a writer needs. */
+type WritableSocket = {
+    write(data: Uint8Array): number;
+};
+/**
+ * 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 declare function createSocketWriter(socket: WritableSocket): {
+    write(text: string): void;
+    drain(): void;
+};
+export {};