hyperbrane 0.1.2 → 0.2.1

package/dist/agent/api.d.ts

@@ -1,157 +1,158 @@
-import type { ModelInfo, SDKBackgroundTasksChangedMessage, PermissionResult, SDKAssistantMessage, SDKPartialAssistantMessage, SDKResultMessage, SDKSystemMessage, SDKUserMessage } from "../vendor-types/claude/agent-sdk/sdk.js";
+import type { ModelInfo, SDKBackgroundTasksChangedMessage, PermissionResult, SDKAssistantMessage, SDKCompactBoundaryMessage, 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 declare const AGENT_PERMISSION_MODES: readonly ["ask", "auto"];
+export type AgentPermissionMode = (typeof AGENT_PERMISSION_MODES)[number];
 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 AgentSessionUpdate = Partial<Omit<AgentSession, "name">>;
+export type AgentSessionState = ({
+    readonly state: "exited";
+    readonly code: number | null;
+    readonly signal: string | null;
+    readonly error?: string;
+} | {
+    readonly state: "installing";
+    readonly backend: AgentBackend;
+    readonly version: string;
+} | {
+    readonly state: "starting";
+} | {
+    readonly state: "waiting";
+} | {
+    readonly state: "idle";
+} | {
+    readonly state: "tool";
+    readonly tools: readonly string[];
+} | {
+    readonly state: "thinking";
+}) & {
+    readonly since?: number;
+};
+export type AgentStatusMessage = {
+    readonly type: "session_status";
+    readonly status: AgentSessionState;
+};
+export type AgentPromptFailedMessage = {
+    readonly type: "prompt_failed";
+    readonly uuid: string;
+    readonly error: string;
+};
+export type AgentNoticeMessage = {
+    readonly type: "session_notice";
+    readonly text: string;
+};
+export type AgentCompactionMessage = Omit<SDKCompactBoundaryMessage, "compact_metadata"> & {
+    readonly compact_metadata?: SDKCompactBoundaryMessage["compact_metadata"];
+    readonly timestamp?: string;
+};
+export type AgentSessionEvent = {
+    readonly kind: "review";
+    readonly state: "entered" | "exited";
+    readonly review: string;
+} | {
+    readonly kind: "subagent";
+    readonly activity: "started" | "interacted" | "interrupted" | "completed";
+    readonly agent: string;
+    readonly path: string;
+};
+export type AgentEventMessage = {
+    readonly type: "system";
+    readonly subtype: "session_event";
+    readonly event: AgentSessionEvent;
+    readonly uuid: string;
+    readonly session_id: string;
+    readonly timestamp?: string;
+};
+export type AgentAssistantMessage = SDKAssistantMessage & {
+    readonly phase?: "commentary" | "final";
+    readonly async?: true;
+};
 export type AgentSessionInfo = AgentSession & {
     readonly agentName: string;
     readonly status: AgentSessionState;
-    /** The backend's own id for the conversation (claude's session id, codex's thread id), once known. */
     readonly nativeId: string | null;
-    /** Chosen through AgentModels; null for the backend's default. */
     readonly model: string | null;
+    readonly permissionMode: AgentPermissionMode;
 };
-/** Where a session lives: sessions are named per agent. */
 export type SessionRef = {
     agentName: string;
     sessionName: string;
 };
 /** @sealed */
 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. */
+    updateSession(ref: SessionRef, update: AgentSessionUpdate): Promise<AgentSessionInfo>;
     listSessions(): Promise<AgentSessionInfo[]>;
-    /** DELETE /v1/agents/:agentName/sessions/:sessionName — ends the CLI and forgets the session. */
     stopSession(ref: SessionRef): Promise<void>;
+    restoreAgents(): Promise<string[]>;
 }
 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 & {
+export type AgentStreamingMessage = SDKSystemMessage | AgentAssistantMessage | SDKPartialAssistantMessage | (SDKUserMessage & {
     uuid: string;
     session_id: string;
-}) | SDKResultMessage;
-/** A complete message of the conversation so far (no partial output), as the stream carried it. */
+}) | SDKResultMessage | AgentCompactionMessage | AgentEventMessage | AgentStatusMessage | AgentPromptFailedMessage | AgentNoticeMessage;
 export type AgentTranscriptMessage = Extract<AgentStreamingMessage, {
     type: "user" | "assistant";
-}>;
+}> | AgentCompactionMessage | AgentEventMessage;
 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;
-    /**
-     * An ISO 8601 time: the page holds the newest messages from before it (a page's `nextBefore`, for
-     * the page before that one); omitted for the newest page.
-     */
     before?: string;
-    /** @deprecated `before` by its old name: a page's `nextCursor` is its `nextBefore`. */
+    toolUseId?: string;
+    /** @deprecated */
     cursor?: string;
 };
-/**
- * Newest pages first; each page's messages oldest first. `nextBefore` is the time of its oldest
- * message, when there are older ones: every message of that time is on this page.
- */
 export type AgentTranscriptPage = {
     readonly messages: AgentTranscriptMessage[];
     readonly nextBefore: string | null;
-    /** @deprecated `nextBefore` by its old name, for requests that give it as `cursor`. */
+    /** @deprecated */
     readonly 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 = {
     readonly id: string;
     readonly tool_name: string;
     readonly input: Record<string, unknown>;
     readonly tool_use_id: string;
-    /** Why the agent asks, when it says (e.g. codex's reason for wanting network access). */
     readonly 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"> & {
     readonly options: AskUserQuestion["options"][number][];
 };
-/** The agent asking the user something (claude's AskUserQuestion, codex's request_user_input). */
 export type AgentQuestionRequest = {
     readonly id: string;
     readonly tool_use_id: string;
     readonly 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 = {
     readonly state: "signedIn";
 } | {
-    readonly state: "signedOut"; /** Why the last sign-in failed, if one did. */
+    readonly state: "signedOut";
     readonly error?: string;
 } | {
     readonly state: "pending";
@@ -159,156 +160,108 @@ export type AgentAuthStatus = {
     readonly userCode?: string;
     readonly needsCode: boolean;
 };
-/**
- * A backend in an agent's dimension: the version installed (null: none), and whether it's ready to
- * run, i.e. this release's version, complete. Kept in the dimension's state directory, so it lasts as
- * long as the dimension, its container recreated or not.
- */
 export type AgentBackendInfo = {
     readonly backend: AgentBackend;
     readonly version: string | null;
     readonly ready: boolean;
+    readonly pinned: string;
 };
 /** @sealed */
 export interface AgentProvision {
-    /**
-     * POST /v1/agents/:agentName/backends/:backend/install — installs the backend in the dimension, or
-     * updates it, or completes it; nothing to do when it's ready. Downloads through the dimension's portals.
-     */
     install(agentName: string, backend: AgentBackend): Promise<void>;
-    /** GET /v1/agents/:agentName/backends — each backend, as installed in the agent's dimension. */
     listBackends(agentName: string): Promise<AgentBackendInfo[]>;
 }
 /** @sealed */
-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`. Its URL lasts, but the proxy behind it doesn't: an archived and resumed Boat
-     * sandbox, or a reboot, stops it, and a page connecting then gets what a browser reports as a CORS
-     * error. This call (three round trips to the host when nothing changed) starts the agent's worker
-     * and the endpoint's proxy again if they stopped, keeping the same URL and credentials: give
-     * workerSseConnector a function that calls it, and it calls it again whenever a connection fails
-     * to open; an endpoint kept elsewhere goes stale. Origins add up: those given join the endpoint's own, in place, so
-     * pages already connected stay connected, and a call with fewer (or none) removes nothing. A new
-     * endpoint only for another scheme, or once the old one can't be served (its port taken); the old
-     * one's connections end then. Closed with the agent. Needs a host that declares endpoints.
-     */
-    exposeAgent(agentName: string, scheme: SandboxEndpointScheme, allowedOrigins?: string[]): Promise<SandboxEndpoint>;
-}
-/** @sealed */
 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>;
 }
 /** @sealed */
 export interface AgentTranscript {
-    /**
-     * GET /v1/agents/:agentName/sessions/:sessionName/transcript?limit=&before= (or &cursor=, its old name) — 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>;
 }
 /** @sealed */
 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>;
 }
 /** @sealed */
 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>;
 }
 /** @sealed */
 export interface AgentSessionStatus {
-    /** GET /v1/agents/:agentName/sessions/:sessionName/status */
     getSessionStatus(ref: SessionRef): Promise<AgentSessionState>;
 }
 /** @sealed */
 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[]>;
 }
 /** @sealed */
 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>;
 }
 /** @sealed */
 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>;
 }
 /** @sealed */
 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>;
 }
 /** @sealed */
 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>;
 }
 /** @sealed */
 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). */
+/** @sealed */
+export interface AgentPermissionModes {
+    setPermissionMode(ref: SessionRef, mode: AgentPermissionMode): Promise<void>;
+}
+export type AgentModelUsage = {
+    readonly model: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+    readonly costUsd: number | null;
+};
+export type AgentTurnUsage = {
+    readonly id: string;
+    readonly startedAt: string;
+    readonly endedAt: string;
+    readonly models: AgentModelUsage[];
+    readonly costUsd: number | null;
+};
+/** @sealed */
+export interface AgentUsage {
+    getUsage(ref: SessionRef): Promise<AgentTurnUsage[]>;
+}
+export type AgentSessionCapabilities = AgentStream & AgentTranscript & AgentInterrupt & AgentInput & AgentSessionStatus & AgentMessageQueue & AgentPermissions & AgentQuestions & AgentBackgroundTasks & AgentAuth & AgentModels & AgentPermissionModes & AgentUsage;
+/** @sealed */
+export interface DimensionAgentClient extends Pick<AgentClient, "createSession" | "updateSession" | "listSessions" | "stopSession">, AgentProvision, AgentSessionCapabilities {
+    listAgents(): Promise<string[]>;
+}
 export type AgentLastUserMessage = {
     readonly message: UserMessage;
     readonly 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;
 }
-/**
- * The session's backend isn't installed in its dimension, or not completely (AgentBackendInfo.ready):
- * AgentProvision.install puts it there. A conflict with the dimension's state, so caught as one too.
- */
 export declare class AgentBackendNotInstalledError extends AgentConflictError {
     name: string;
 }

package/dist/agent/api.js

@@ -1,21 +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 const AGENT_PERMISSION_MODES = ["ask", "auto"];
 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";
 }
-/**
- * The session's backend isn't installed in its dimension, or not completely (AgentBackendInfo.ready):
- * AgentProvision.install puts it there. A conflict with the dimension's state, so caught as one too.
- */
 export class AgentBackendNotInstalledError extends AgentConflictError {
     name = "AgentBackendNotInstalledError";
 }

package/dist/agent/client.d.ts

@@ -1,3 +1,5 @@
 export { createWorkerClient, type WorkerClient } from "./session/client.ts";
 export { sharedConnector, type SharedConnector } from "./session/sharedConnection.ts";
-export { EndpointLoginRequiredError, EndpointUnreachableError, exeDevLoginUrl, workerSseConnector, type WorkerEndpoint } from "./session/workerSseConnection.ts";
+export type { ConnectWorker } from "./session/workerConnection.ts";
+export { EndpointCredentialsError, EndpointUnreachableError, workerGatewayConnector } from "./session/workerGatewayConnection.ts";
+export { WorkerErrorCode } from "./session/worker/protocol.ts";

package/dist/agent/client.js

@@ -1,5 +1,4 @@
-// An agent's worker, reached through its endpoint (AgentService.exposeAgent): what a browser can
-// import (hyperbrane/agent/client), since the root module brings the server side with it.
 export { createWorkerClient } from "./session/client.js";
 export { sharedConnector } from "./session/sharedConnection.js";
-export { EndpointLoginRequiredError, EndpointUnreachableError, exeDevLoginUrl, workerSseConnector } from "./session/workerSseConnection.js";
+export { EndpointCredentialsError, EndpointUnreachableError, workerGatewayConnector } from "./session/workerGatewayConnection.js";
+export { WorkerErrorCode } from "./session/worker/protocol.js";

package/dist/agent/control.d.ts

@@ -0,0 +1,23 @@
+import type { Sandbox } from "../sandbox/api.ts";
+import { type Agent, type AgentBackend, type AgentBackendInfo, type AgentSessionInfo, type SessionRef } from "./api.ts";
+export declare const WORKER_DIR: string;
+export type ControlOptions = {
+    dataDirectory?: string;
+};
+export declare function createAgentScript(host: Sandbox, agent: Agent, options?: ControlOptions & {
+    replaceBuild?: boolean;
+}): Promise<void>;
+export declare function stopAgentScript(host: Sandbox, agentName: string, options?: ControlOptions): Promise<void>;
+export declare function listAgentsScript(host: Sandbox, options?: ControlOptions): Promise<Agent[]>;
+export declare function listSessionsScript(host: Sandbox, options?: ControlOptions): Promise<AgentSessionInfo[]>;
+export declare function installScript(host: Sandbox, agentName: string, backend: AgentBackend, options?: ControlOptions): Promise<void>;
+export declare function loginStateScript(host: Sandbox, ref: SessionRef, options?: ControlOptions): Promise<{
+    backend: AgentBackend;
+    gatewaySignedIn: boolean;
+}>;
+export declare function agentsDownScript(host: Sandbox, options?: ControlOptions): Promise<Agent[]>;
+export declare function workerSocketScript(host: Sandbox, agentName: string, options?: ControlOptions): Promise<{
+    dimensionName: string;
+    socket: string;
+}>;
+export declare function listBackendsScript(host: Sandbox, agentName: string, options?: ControlOptions): Promise<AgentBackendInfo[]>;