hyperbrane 0.1.2 → 0.2.1

package/dist/agent/control.js

@@ -0,0 +1,479 @@
+import { dimensionLayout } from "../dimension/api.js";
+import { sh } from "../lib/sh.js";
+import { AGENT_BACKENDS, AgentConflictError, AgentNotFoundError, } from "./api.js";
+import { codexPackage } from "./session/codex/provision.js";
+import { WORKER_PROTOCOL } from "./session/worker/protocol.js";
+import { claudePackage } from "./session/claude/provision.js";
+import { workerBundle } from "./workerBundle.js";
+export const WORKER_DIR = `${dimensionLayout.statePath()}/worker`;
+const OLD_WORKER_DIR = "/opt/hyperbrane/worker";
+const SCRIPTS_DIR = "/opt/hyperbrane";
+const START_TIMEOUT_S = 30;
+const STOP_TIMEOUT_S = 10;
+const EXIT = { noDimension: 40, notRunning: 41, oldDimension: 42, conflict: 43, noAgent: 44, thirdUser: 45, needBundle: 46, noSession: 47 };
+const AUTH_UPSTREAMS = { claude: "anthropic", codex: "openai" };
+function backendPackage(backend) {
+    return backend === "claude" ? claudePackage() : codexPackage();
+}
+export async function createAgentScript(host, agent, options = {}) {
+    const bundle = await workerBundle();
+    const env = {
+        ...dimensionEnv(agent.dimensionName, options),
+        ...(options.replaceBuild ? { REPLACE_BUILD: "1" } : {}),
+        AGENT: agent.name,
+        BUILD: bundle.build,
+        PROTOCOL: String(WORKER_PROTOCOL),
+        CA_BUNDLE: dimensionLayout.caBundlePath(),
+        START_TIMEOUT: String(START_TIMEOUT_S),
+        STOP_TIMEOUT: String(STOP_TIMEOUT_S),
+    };
+    let result = await run(host, CREATE_AGENT, env);
+    if (result.exitCode === EXIT.needBundle)
+        result = await run(host, CREATE_AGENT, { ...env, HAS_BUNDLE: "1" }, bundle.source);
+    check(result, `starting agent ${agent.name}`, agent);
+}
+export async function stopAgentScript(host, agentName, options = {}) {
+    const result = await run(host, STOP_AGENT, { ...dataEnv(options), AGENT: agentName, STOP_TIMEOUT: String(STOP_TIMEOUT_S) });
+    check(result, `stopping agent ${agentName}`);
+}
+export async function listAgentsScript(host, options = {}) {
+    const result = check(await run(host, LIST_AGENTS, dataEnv(options)), "listing agents");
+    return records(result.stdout).map(([, agent]) => agent);
+}
+export async function listSessionsScript(host, options = {}) {
+    const result = check(await run(host, LIST_SESSIONS, dataEnv(options)), "listing sessions");
+    const running = new Set(result.stdout
+        .split("\n")
+        .filter((line) => line.startsWith("running "))
+        .map((line) => line.slice("running ".length)));
+    return records(result.stdout).map(([header, record]) => {
+        const [agentName = "", saved = ""] = header.split("\t");
+        const status = !running.has(agentName) ? { state: "exited", code: null, signal: null } : (savedStatus(saved) ?? { state: "idle" });
+        return { ...record.spec, agentName, status, nativeId: record.nativeId, model: record.model, permissionMode: record.permissionMode ?? "ask" };
+    });
+}
+export async function installScript(host, agentName, backend, options = {}) {
+    const { pkg, version, executables } = backendPackage(backend);
+    const env = { ...dataEnv(options), AGENT: agentName, PKG: pkg, VERSION: version, EXECUTABLES: executables, CA_BUNDLE: dimensionLayout.caBundlePath() };
+    check(await run(host, INSTALL_BACKEND, env), `installing ${backend} for agent ${agentName}`);
+}
+export async function loginStateScript(host, ref, options = {}) {
+    const upstreams = Object.entries(AUTH_UPSTREAMS)
+        .map(([backend, upstream]) => `${backend}\t${upstream}`)
+        .join("\n");
+    const result = check(await run(host, LOGIN_STATE, { ...dataEnv(options), AGENT: ref.agentName, SESSION: ref.sessionName, UPSTREAMS: upstreams }), `signing in ${ref.agentName}/${ref.sessionName}`);
+    const [backend = "", signedIn] = result.stdout.trim().split("\t");
+    if (!AGENT_BACKENDS.includes(backend))
+        throw new Error(`session ${ref.sessionName} has no known backend (${backend})`);
+    return { backend: backend, gatewaySignedIn: signedIn === "1" };
+}
+export async function agentsDownScript(host, options = {}) {
+    const result = check(await run(host, AGENTS_DOWN, dataEnv(options)), "finding agents to restore");
+    return result.stdout
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+        const [name = "", dimensionName = ""] = line.split("\t");
+        return { name, dimensionName };
+    });
+}
+export async function workerSocketScript(host, agentName, options = {}) {
+    const result = check(await run(host, WORKER_SOCKET, { ...dataEnv(options), AGENT: agentName }), `finding agent ${agentName}'s worker`);
+    const [dimensionName = "", socket = ""] = result.stdout.split("\n");
+    return { dimensionName, socket };
+}
+export async function listBackendsScript(host, agentName, options = {}) {
+    const lines = AGENT_BACKENDS.map((backend) => {
+        const { pkg, version, executables } = backendPackage(backend);
+        return [backend, pkg, version, executables].join("\t");
+    });
+    const result = check(await run(host, LIST_BACKENDS, { ...dataEnv(options), AGENT: agentName, BACKENDS: lines.join("\n") }), "listing backends");
+    return result.stdout
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+        const [backend, installed = "", ready] = line.split("\t");
+        return { backend: backend, version: installed || null, ready: ready === "1", pinned: backendPackage(backend).version };
+    });
+}
+function dataEnv({ dataDirectory }) {
+    return {
+        ...(dataDirectory === undefined ? {} : { DATA: dataDirectory }),
+        CONTAINER_PREFIX: dimensionLayout.containerName(""),
+        RUN_PATH: dimensionLayout.runPath(),
+        STATE_PATH: dimensionLayout.statePath(),
+        WORKER_DIR,
+        SCRIPTS_DIR,
+        OLD_WORKER_DIR,
+        ...Object.fromEntries(Object.entries(EXIT).map(([name, code]) => [`E_${name.replace(/[A-Z]/g, (c) => `_${c}`).toUpperCase()}`, String(code)])),
+    };
+}
+function dimensionEnv(dimensionName, options) {
+    return { ...dataEnv(options), DIMENSION: dimensionName };
+}
+function run(host, script, env, stdin) {
+    const inDimension = { KILL_AGENT, PREPARE_WORKER, PUT_SCRIPT, START_WORKER, REMOVE_OLD_SCRIPTS, INSTALL_IN_DIMENSION };
+    return host.runCommand(["sh", "-c", `${PRELUDE}\n${script}`], { env: { ...inDimension, ...env }, stdin });
+}
+function check(result, what, agent) {
+    const said = result.stderr.trim();
+    switch (result.exitCode) {
+        case 0:
+            return result;
+        case EXIT.noDimension:
+            throw new AgentNotFoundError(`dimension ${agent?.dimensionName ?? said} does not exist`);
+        case EXIT.notRunning:
+            throw new AgentConflictError(`dimension ${agent?.dimensionName ?? said} is not running`);
+        case EXIT.oldDimension:
+            throw new AgentConflictError(`dimension ${agent?.dimensionName ?? said} lacks the ${dimensionLayout.runPath()} and ${dimensionLayout.statePath()} mounts agents need (it predates them); recreate it`);
+        case EXIT.conflict:
+            throw new AgentConflictError(`agent ${agent?.name ?? ""} already exists in another dimension: ${said}`);
+        case EXIT.noAgent:
+            throw new AgentNotFoundError(`agent ${said} does not exist`);
+        case EXIT.noSession:
+            throw new AgentNotFoundError(`session ${said} does not exist`);
+        case EXIT.thirdUser:
+            throw new AgentConflictError(`${what}: ${said}`);
+        default:
+            throw new Error(`${what} failed (exit ${result.exitCode}): ${said || result.stdout.trim()}`);
+    }
+}
+function records(stdout) {
+    return stdout
+        .split(RECORD_END)
+        .map((block) => block.replace(/^(running [^\n]*\n)+/, ""))
+        .filter((block) => block.trim())
+        .flatMap((block) => {
+        const newline = block.indexOf("\n");
+        try {
+            return [[block.slice(0, newline), JSON.parse(block.slice(newline + 1))]];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+function savedStatus(file) {
+    try {
+        const { status } = JSON.parse(file);
+        if (!status)
+            return null;
+        if (status.state === "tool")
+            return Array.isArray(status.tools) ? status : null;
+        return SESSION_STATES.has(status.state) ? status : null;
+    }
+    catch {
+        return null;
+    }
+}
+const SESSION_STATES = new Set(["exited", "starting", "waiting", "idle", "thinking"]);
+const RECORD_END = "\n\x1e\n";
+const PRELUDE = sh `
+DATA="\${DATA:-$HOME/.local/share/hyperbrane}"
+
+agent_dimension() {
+  record="$DATA/agents/$1.json"
+  if [ ! -f "$record" ]; then
+    echo "$1" >&2
+    exit "$E_NO_AGENT"
+  fi
+  DIMENSION="$(sed -n 's/^ *"dimensionName": *"\([^"]*\)".*/\1/p' "$record")"
+}
+
+# Exits unless dimension $DIMENSION exists and runs, with the mounts agents need. Sets CONTAINER,
+# DIMENSION_USER (whom it runs as, uid[:gid]) and RUN (its run directory on the machine).
+require_dimension() {
+  CONTAINER="$CONTAINER_PREFIX$DIMENSION"
+  RUN="$DATA/dimension-run/$DIMENSION"
+  format='{{index .Config.Labels "hyperbrane.dimension"}}|{{.State.Running}}|{{range .Mounts}}{{.Destination}},{{end}}|{{.Config.User}}'
+  if ! info="$(docker inspect -f "$format" "$CONTAINER" 2>/dev/null)"; then
+    echo "$DIMENSION" >&2
+    exit "$E_NO_DIMENSION"
+  fi
+  IFS='|' read -r label running mounts DIMENSION_USER <<INFO
+$info
+INFO
+  if [ "$label" != "$DIMENSION" ]; then
+    echo "$DIMENSION" >&2
+    exit "$E_NO_DIMENSION"
+  fi
+  if [ "$running" != true ]; then
+    echo "$DIMENSION" >&2
+    exit "$E_NOT_RUNNING"
+  fi
+  case "$mounts" in
+    *"$RUN_PATH,"*"$STATE_PATH,"* | *"$STATE_PATH,"*"$RUN_PATH,"*) ;;
+    *)
+      echo "$DIMENSION" >&2
+      exit "$E_OLD_DIMENSION"
+      ;;
+  esac
+  DIMENSION_USER="\${DIMENSION_USER:-0:0}"
+}
+
+# Whether agent $1's worker runs, of any build, and can be reached: its ready file names a live
+# shellcheck disable=SC2034
+worker_running() {
+  WORKER_PID=""
+  WORKER_BUILD=""
+  WORKER_PROTOCOL=""
+  [ -f "$RUN/$1.ready" ] && [ -S "$RUN/$1.sock" ] || return 1
+  read -r WORKER_PID WORKER_BUILD WORKER_PROTOCOL < "$RUN/$1.ready" || return 1
+  docker exec -u 0 "$CONTAINER" grep -qs "hyperbrane/worker" "/proc/$WORKER_PID/cmdline"
+}
+
+stop_worker() {
+  if worker_running "$1"; then
+    docker exec -u 0 "$CONTAINER" kill "$WORKER_PID" 2>/dev/null || true
+    waited=0
+    while [ "$waited" -lt "$STOP_TIMEOUT" ] && docker exec -u 0 "$CONTAINER" kill -0 "$WORKER_PID" 2>/dev/null; do
+      sleep 1
+      waited=$((waited + 1))
+    done
+  fi
+  docker exec -u "$DIMENSION_USER" -e AGENT="$1" "$CONTAINER" sh -c "$KILL_AGENT"
+  rm -f "$RUN/$1.ready" 2>/dev/null || true
+}
+`;
+const KILL_AGENT = sh `
+for process in /proc/[0-9]*; do
+  if tr '\0' '\n' < "$process/environ" 2>/dev/null | grep -qx "HYB_AGENT=$AGENT"; then
+    kill -9 "\${process#/proc/}" 2>/dev/null || true
+  fi
+done
+`;
+const PREPARE_WORKER = sh `
+set -eu
+mkdir -p "$WORKER_DIR" "$SCRIPTS_DIR"
+chown "$OWNER" "$WORKER_DIR" "$SCRIPTS_DIR" "$RUN_PATH" "$STATE_PATH"
+if [ ! -e "$WORKER_DIR/node_modules" ] && [ -d "$OLD_WORKER_DIR/node_modules" ]; then
+  cp -a "$OLD_WORKER_DIR/." "$WORKER_DIR/"
+  rm -rf "$OLD_WORKER_DIR"
+fi
+if [ ! -f "$WORKER_DIR/package.json" ]; then
+  printf '{\n  "name": "hyperbrane-worker",\n  "private": true\n}\n' > "$WORKER_DIR/package.json"
+  chown "$OWNER" "$WORKER_DIR/package.json"
+fi
+printf '[install]\ncafile = "%s"\n' "$CA_BUNDLE" > "$WORKER_DIR/bunfig.toml"
+chown "$OWNER" "$WORKER_DIR/bunfig.toml"
+`;
+const PUT_SCRIPT = sh `
+set -eu
+cat > "$SCRIPT.part"
+mv -f "$SCRIPT.part" "$SCRIPT"
+`;
+const START_WORKER = sh `
+HOME="$(getent passwd "$(id -u)" | cut -d: -f6)"
+export HOME
+cd "$HOME" 2>/dev/null || cd /
+exec bun "$HYB_WORKER_SCRIPT" >> "$HYB_LOG" 2>&1 < /dev/null
+`;
+const REMOVE_OLD_SCRIPTS = sh `
+for old in "$SCRIPTS_DIR"/worker-*.js; do
+  [ "$old" = "$SCRIPTS_DIR/worker-$BUILD.js" ] || rm -f "$old"
+done
+`;
+const CREATE_AGENT = sh `
+set -eu
+DIMENSION_WANTED="$DIMENSION"
+require_dimension
+
+mkdir -p "$DATA/agents"
+record="$DATA/agents/$AGENT.json"
+if [ ! -f "$record" ]; then
+  printf '{\n  "name": "%s",\n  "dimensionName": "%s"\n}\n' "$AGENT" "$DIMENSION" > "$record.$$"
+  ln "$record.$$" "$record" 2>/dev/null || true
+  rm -f "$record.$$"
+fi
+agent_dimension "$AGENT"
+if [ "$DIMENSION" != "$DIMENSION_WANTED" ]; then
+  echo "$DIMENSION" >&2
+  exit "$E_CONFLICT"
+fi
+
+mkdir -p "$RUN"
+exec 8> "$RUN/$AGENT.start.lock"
+flock -w "$((START_TIMEOUT + STOP_TIMEOUT + 30))" 8
+
+if worker_running "$AGENT" && { [ "$WORKER_PROTOCOL" -gt "$PROTOCOL" ] 2> /dev/null || { [ "$WORKER_PROTOCOL" = "$PROTOCOL" ] && { [ -z "\${REPLACE_BUILD:-}" ] || [ "$WORKER_BUILD" = "$BUILD" ]; }; }; }; then exit 0; fi
+
+runs_as="\${DIMENSION_USER%%:*}"
+SOCKET_OWNER=""
+if [ "$runs_as" = 0 ]; then
+  SOCKET_OWNER="$(id -u):$(id -g)"
+elif [ "$runs_as" != "$(id -u)" ]; then
+  echo "agent $AGENT's worker would run as uid $runs_as, whose socket uid $(id -u) can't connect to" >&2
+  exit "$E_THIRD_USER"
+fi
+
+docker exec -u 0 -e OWNER="$DIMENSION_USER" -e WORKER_DIR -e SCRIPTS_DIR -e OLD_WORKER_DIR -e RUN_PATH -e STATE_PATH -e CA_BUNDLE \
+  "$CONTAINER" sh -c "$PREPARE_WORKER"
+
+script="$SCRIPTS_DIR/worker-$BUILD.js"
+if ! docker exec "$CONTAINER" test -f "$script"; then
+  [ "\${HAS_BUNDLE:-}" = 1 ] || exit "$E_NEED_BUNDLE"
+  docker exec -i -u "$DIMENSION_USER" -e SCRIPT="$script" "$CONTAINER" sh -c "$PUT_SCRIPT"
+fi
+
+stop_worker "$AGENT"
+docker exec -d -u "$DIMENSION_USER" \
+  -e HYB_AGENT="$AGENT" -e HYB_LOG="$RUN_PATH/$AGENT.log" -e HYB_INSTALL_DIR="$WORKER_DIR" \
+  -e HYB_WORKER_SCRIPT="$script" -e HYB_WORKER_BUILD="$BUILD" -e HYB_SOCKET_OWNER="$SOCKET_OWNER" \
+  -e NODE_EXTRA_CA_CERTS="$CA_BUNDLE" -e SSL_CERT_FILE="$CA_BUNDLE" \
+  "$CONTAINER" sh -c "$START_WORKER"
+
+waited=0
+until worker_running "$AGENT" && [ "$WORKER_BUILD" = "$BUILD" ]; do
+  if [ "$waited" -ge "$((START_TIMEOUT * 10))" ]; then
+    echo "agent $AGENT's worker did not come up:" >&2
+    tail -c 2000 "$RUN/$AGENT.log" >&2 2>/dev/null || true
+    exit 1
+  fi
+  sleep 0.1
+  waited=$((waited + 1))
+done
+docker exec -u 0 -e SCRIPTS_DIR -e BUILD "$CONTAINER" sh -c "$REMOVE_OLD_SCRIPTS"
+`;
+const STOP_AGENT = sh `
+set -eu
+[ -f "$DATA/agents/$AGENT.json" ] || exit 0
+agent_dimension "$AGENT"
+require_dimension
+stop_worker "$AGENT"
+rm -f "$DATA/agents/$AGENT.json"
+`;
+const WORKER_SOCKET = sh `
+set -eu
+agent_dimension "$AGENT"
+printf '%s\n%s\n' "$DIMENSION" "$DATA/dimension-run/$DIMENSION/$AGENT.sock"
+`;
+const LIST_AGENTS = sh `
+for record in "$DATA"/agents/*.json; do
+  [ -f "$record" ] || continue
+  name="\${record##*/}"
+  printf '%s\n' "\${name%.json}"
+  cat "$record"
+  printf '\n\036\n'
+done
+`;
+const LIST_SESSIONS = sh `
+checks="$(mktemp -d)"
+for record in "$DATA"/agents/*.json; do
+  [ -f "$record" ] || continue
+  agent="\${record##*/}"
+  agent="\${agent%.json}"
+  agent_dimension "$agent"
+  for session in "$DATA/dimension-state/$DIMENSION/agents/$agent/sessions"/*.json; do
+    [ -f "$session" ] || continue
+    status="$(tr -d '\n' < "\${session%.json}/status.json" 2>/dev/null || true)"
+    printf '%s\t%s\n' "$agent" "$status"
+    cat "$session"
+    printf '\n\036\n'
+  done
+  (
+    # shellcheck disable=SC2034
+    CONTAINER="$CONTAINER_PREFIX$DIMENSION"
+    # shellcheck disable=SC2034
+    RUN="$DATA/dimension-run/$DIMENSION"
+    if worker_running "$agent"; then echo "running $agent" > "$checks/$agent"; fi
+  ) &
+done
+wait
+cat "$checks"/* 2>/dev/null || true
+rm -rf "$checks"
+`;
+const INSTALL_IN_DIMENSION = sh `
+set -eu
+cd "$WORKER_DIR"
+HOME="$(getent passwd "$(id -u)" | cut -d: -f6)"
+export HOME
+exec 9> .install.lock
+flock 9
+installed() {
+  manifest="node_modules/$PKG/package.json"
+  [ -f "$manifest" ] || return 1
+  grep -q "\"version\": *\"$VERSION\"" "$manifest" || return 1
+  # shellcheck disable=SC2086
+  for executable in $EXECUTABLES; do
+    for found in node_modules/$executable; do
+      [ -x "$found" ] && return 0
+    done
+  done
+  return 1
+}
+installed && exit 0
+force=""
+if [ -f "node_modules/$PKG/package.json" ] && grep -q "\"version\": *\"$VERSION\"" "node_modules/$PKG/package.json"; then force=--force; fi
+# shellcheck disable=SC2086
+bun add --exact $force "$PKG@$VERSION"
+installed || { echo "bun add $PKG@$VERSION left no executable ($EXECUTABLES)" >&2; exit 1; }
+`;
+const INSTALL_BACKEND = sh `
+set -eu
+agent_dimension "$AGENT"
+require_dimension
+docker exec -u "$DIMENSION_USER" -e WORKER_DIR -e PKG -e VERSION -e EXECUTABLES \
+  -e NODE_EXTRA_CA_CERTS="$CA_BUNDLE" -e SSL_CERT_FILE="$CA_BUNDLE" "$CONTAINER" sh -c "$INSTALL_IN_DIMENSION"
+`;
+const LIST_BACKENDS = sh `
+set -eu
+agent_dimension "$AGENT"
+modules="$DATA/dimension-state/$DIMENSION/worker/node_modules"
+tab="$(printf '\t')"
+printf '%s\n' "$BACKENDS" | while IFS="$tab" read -r backend pkg _pinned executables; do
+  installed="$(sed -n 's/^ *"version": *"\([^"]*\)".*/\1/p' "$modules/$pkg/package.json" 2>/dev/null | head -n 1)"
+  ready=0
+  if [ -n "$installed" ]; then
+    # shellcheck disable=SC2086
+    for executable in $executables; do
+      for found in "$modules"/$executable; do
+        [ -x "$found" ] && ready=1
+      done
+    done
+  fi
+  printf '%s\t%s\t%s\n' "$backend" "$installed" "$ready"
+done
+`;
+const LOGIN_STATE = sh `
+set -eu
+agent_dimension "$AGENT"
+record="$DATA/dimension-state/$DIMENSION/agents/$AGENT/sessions/$SESSION.json"
+if [ ! -f "$record" ]; then
+  echo "$SESSION" >&2
+  exit "$E_NO_SESSION"
+fi
+backend="$(sed -n 's/^ *"backend": *"\([^"]*\)".*/\1/p' "$record" | head -n 1)"
+tab="$(printf '\t')"
+upstream="$(printf '%s\n' "$UPSTREAMS" | while IFS="$tab" read -r name value; do
+  if [ "$name" = "$backend" ]; then echo "$value"; fi
+done)"
+signed=0
+for portal in "$DATA"/portals/*.json; do
+  [ -f "$portal" ] || continue
+  grep -q "\"dimensionName\": *\"$DIMENSION\"" "$portal" || continue
+  gateway="$(sed -n 's/^ *"gatewayName": *"\([^"]*\)".*/\1/p' "$portal")"
+  state="$DATA/gateway-state/$gateway"
+  if [ -n "$upstream" ] && [ -f "$state/upstreams/$upstream.json" ] && [ -f "$state/credentials/$upstream.oauth.json" ]; then signed=1; fi
+done
+printf '%s\t%s\n' "$backend" "$signed"
+`;
+const AGENTS_DOWN = sh `
+checks="$(mktemp -d)"
+for record in "$DATA"/agents/*.json; do
+  [ -f "$record" ] || continue
+  agent="\${record##*/}"
+  agent="\${agent%.json}"
+  agent_dimension "$agent"
+  (
+    CONTAINER="$CONTAINER_PREFIX$DIMENSION"
+    # shellcheck disable=SC2034
+    RUN="$DATA/dimension-run/$DIMENSION"
+    [ "$(docker inspect -f '{{.State.Running}}' "$CONTAINER" 2>/dev/null)" = true ] || exit 0
+    worker_running "$agent" && exit 0
+    printf '%s\t%s\n' "$agent" "$DIMENSION" > "$checks/$agent"
+  ) &
+done
+wait
+cat "$checks"/* 2>/dev/null || true
+rm -rf "$checks"
+`;

package/dist/agent/dimensionAgentClient.d.ts

@@ -0,0 +1,8 @@
+import { type DimensionAgentClient, type SessionRef } from "./api.ts";
+export type DimensionDirectories = {
+    runDirectory: string;
+    stateDirectory: string;
+};
+export declare function createDimensionAgentClient(): DimensionAgentClient;
+export declare function currentSession(): SessionRef | null;
+export declare function dimensionAgentClient({ runDirectory, stateDirectory }: DimensionDirectories): DimensionAgentClient;

package/dist/agent/dimensionAgentClient.js

@@ -0,0 +1,99 @@
+import { readdir, stat } from "node:fs/promises";
+import { dimensionLayout } from "../dimension/api.js";
+import { InvalidNameError, checkName } from "../lib/jsonDirectory.js";
+import { SandboxConnectionRefusedError } from "../sandbox/api.js";
+import { connectUnixSocket } from "../lib/unixSocket.js";
+import { AgentConflictError, AgentInvalidError, AgentNotFoundError, } from "./api.js";
+import { createWorkerClient } from "./session/client.js";
+import { workerSocketPath } from "./session/sessionStorage.js";
+import { workerStreamConnector } from "./session/workerConnection.js";
+export function createDimensionAgentClient() {
+    return dimensionAgentClient({ runDirectory: dimensionLayout.runPath(), stateDirectory: dimensionLayout.statePath() });
+}
+export function currentSession() {
+    const { HYB_AGENT: agentName, HYB_SESSION: sessionName } = process.env;
+    return agentName && sessionName ? { agentName, sessionName } : null;
+}
+export function dimensionAgentClient({ runDirectory, stateDirectory }) {
+    function connector(agentName) {
+        const socket = workerSocketPath(runDirectory, agentName);
+        const connect = workerStreamConnector(() => connectUnixSocket(socket), socket);
+        return async (onNotification) => {
+            assertValidName("agent", agentName);
+            try {
+                return await connect(onNotification);
+            }
+            catch (error) {
+                if (!(error instanceof SandboxConnectionRefusedError))
+                    throw error;
+                const known = await stat(`${stateDirectory}/agents/${agentName}`).then(() => true, () => false);
+                if (!known)
+                    throw new AgentNotFoundError(`agent ${agentName} does not exist in this dimension`);
+                throw new AgentConflictError(`agent ${agentName}'s worker isn't running; a call through the machine's agents client starts it`);
+            }
+        };
+    }
+    function clientFor(agentName) {
+        return createWorkerClient(connector(agentName));
+    }
+    const sessionClient = ({ agentName }) => clientFor(agentName);
+    async function listAgents() {
+        const entries = await readdir(runDirectory).catch(() => []);
+        const names = entries.filter((entry) => entry.endsWith(".ready") && !entry.startsWith(".")).map((entry) => entry.slice(0, -".ready".length));
+        const running = await Promise.all(names.map((name) => stat(workerSocketPath(runDirectory, name)).then(() => name, () => null)));
+        return running.filter((name) => name !== null).sort();
+    }
+    async function* getStream(ref, request) {
+        yield* sessionClient(ref).stream(ref.sessionName, request.after_id);
+    }
+    async function listSessions() {
+        const listed = await Promise.all((await listAgents()).map((agentName) => clientFor(agentName)
+            .call("session/list", {})
+            .catch((error) => {
+            if (error instanceof AgentConflictError || error instanceof AgentNotFoundError)
+                return [];
+            throw error;
+        })));
+        return listed.flat();
+    }
+    return {
+        listAgents,
+        listSessions,
+        install: async (agentName, backend) => void (await clientFor(agentName).call("backend/install", { backend })),
+        listBackends: (agentName) => clientFor(agentName).call("backend/list", {}),
+        createSession: (agentName, session) => clientFor(agentName).call("session/create", { session }),
+        updateSession: (ref, update) => sessionClient(ref).call("session/update", { session: ref.sessionName, update }),
+        stopSession: async (ref) => void (await sessionClient(ref).call("session/stop", { session: ref.sessionName })),
+        getStream,
+        getTranscript: (ref, { toolUseId, limit, before } = {}) => toolUseId === undefined
+            ? sessionClient(ref).call("session/transcript", { session: ref.sessionName, limit, before })
+            : sessionClient(ref).call("session/subagentTranscript", { session: ref.sessionName, toolUseId, limit, before }),
+        getUsage: (ref) => sessionClient(ref).call("session/usage", { session: ref.sessionName }),
+        cancel: async (ref) => void (await sessionClient(ref).call("session/interrupt", { session: ref.sessionName })),
+        sendMessage: async (ref, message) => void (await sessionClient(ref).call("session/send", { session: ref.sessionName, message })),
+        getSessionStatus: (ref) => sessionClient(ref).call("session/status", { session: ref.sessionName }),
+        getLastUserMessages: (ref) => sessionClient(ref).call("session/lastUserMessages", { session: ref.sessionName }),
+        listPermissionRequests: (ref) => sessionClient(ref).call("permission/list", { session: ref.sessionName }),
+        respondPermissionRequest: async (ref, request, result) => void (await sessionClient(ref).call("permission/respond", { session: ref.sessionName, request, result })),
+        listQuestionRequests: (ref) => sessionClient(ref).call("question/list", { session: ref.sessionName }),
+        respondQuestionRequest: async (ref, request, response) => void (await sessionClient(ref).call("question/respond", { session: ref.sessionName, request, response })),
+        listModels: (ref) => sessionClient(ref).call("model/list", { session: ref.sessionName }),
+        setModel: async (ref, model) => void (await sessionClient(ref).call("model/set", { session: ref.sessionName, model })),
+        setPermissionMode: async (ref, mode) => void (await sessionClient(ref).call("permission/mode", { session: ref.sessionName, mode })),
+        listBackgroundTasks: (ref) => sessionClient(ref).call("task/list", { session: ref.sessionName }),
+        stopTask: async (ref, task) => void (await sessionClient(ref).call("task/stop", { session: ref.sessionName, task })),
+        getAuthStatus: (ref) => sessionClient(ref).call("auth/status", { session: ref.sessionName }),
+        login: (ref) => sessionClient(ref).call("auth/login", { session: ref.sessionName, gatewaySignedIn: false }),
+        submitAuthCode: (ref, code) => sessionClient(ref).call("auth/code", { session: ref.sessionName, code }),
+    };
+}
+function assertValidName(kind, name) {
+    try {
+        checkName(name);
+    }
+    catch (error) {
+        if (error instanceof InvalidNameError)
+            throw new AgentInvalidError(`invalid ${kind} name: ${error.message}`);
+        throw error;
+    }
+}

package/dist/agent/hostTranscript.d.ts

@@ -1,11 +1,5 @@
 import type { Sandbox } from "../sandbox/api.ts";
 import { type AgentTranscriptPage, type AgentTranscriptRequest } from "./api.ts";
-/**
- * A page of the session's transcript, read on `host` from the dimension's state directory (its host
- * side) by the backend's own layout and parsing, so nothing has to run: one command, plus a read
- * for each further chunk the rare page that needs more takes. Null for a session whose env moves the backend's home
- * elsewhere (into the container, where only its worker reaches it).
- */
 export declare function readHostTranscript(host: Sandbox, { stateDirectory, agentName, sessionName }: {
     stateDirectory: string;
     agentName: string;

package/dist/agent/hostTranscript.js

@@ -2,12 +2,6 @@ import { AgentNotFoundError } from "./api.js";
 import { CHUNK_BYTES, PROBE_BYTES, PROBE_LINES, TIME_SLACK_MS, createFileTranscript, prefetchedFiles, sandboxFiles, transcriptPage, transcriptTime, } from "./session/fileTranscript.js";
 import { backendHomePath, sessionRecordPath } from "./session/sessionStorage.js";
 import { STORED_TRANSCRIPTS } from "./session/storedTranscripts.js";
-/**
- * In one round trip: the session's record, its backend's file (found as the backend lays them out),
- * the stretches written again in it, where the page starts (for a time, by bisecting the rest of the
- * file as FileTranscript.page does) and what comes before that (PREFETCH_BYTES of it). The same
- * searches as fileTranscript.ts, here where the file is. Args: a JSON object, see readHostTranscript.
- */
 const READ_SCRIPT = String.raw `
 import base64, datetime, fnmatch, glob, json, mmap, os, sys
 args = json.loads(sys.argv[1])
@@ -146,16 +140,9 @@ if native_id and layout:
             out.update(path=path, size=size, end=end, after=after, copies=[[a, b] for a, b in copies], pieces=pieces)
 print(json.dumps(out))
 `;
-/** What's sent of the file with the record: a page and the slack around it, mostly, so it takes no more reads. */
 const PREFETCH_BYTES = 8 * CHUNK_BYTES;
-/**
- * A page of the session's transcript, read on `host` from the dimension's state directory (its host
- * side) by the backend's own layout and parsing, so nothing has to run: one command, plus a read
- * for each further chunk the rare page that needs more takes. Null for a session whose env moves the backend's home
- * elsewhere (into the container, where only its worker reaches it).
- */
 export async function readHostTranscript(host, { stateDirectory, agentName, sessionName }, { limit, before, cursor }) {
-    before ??= cursor; // its old name
+    before ??= cursor;
     const args = {
         record: sessionRecordPath(stateDirectory, agentName, sessionName),
         homes: Object.fromEntries(Object.keys(STORED_TRANSCRIPTS).map((backend) => [backend, backendHomePath(stateDirectory, backend)])),
@@ -174,6 +161,8 @@ export async function readHostTranscript(host, { stateDirectory, agentName, sess
     if (!record)
         throw new AgentNotFoundError(`session ${sessionName} does not exist`);
     const stored = STORED_TRANSCRIPTS[record.spec.backend];
+    if (!stored)
+        return null;
     if (Object.keys(stored.homeEnvironment("")).some((name) => record.spec.env?.[name] !== undefined))
         return null;
     if (!record.nativeId)