hyperbrane 0.1.2 → 0.2.0

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" = "$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/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)

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

@@ -1,82 +1,67 @@
-import type { AgentBackendInfo, AgentBackgroundTasks, AgentInput, AgentInterrupt, AgentMessageQueue, AgentModels, AgentPermissionRequest, AgentPermissionResult, AgentQuestionRequest, AgentQuestionResponse, AgentSession, AgentSessionStatus, AgentStreamingMessage, SessionRef } from "../api.ts";
-import type { FileTranscript, TranscriptFiles } from "./fileTranscript.ts";
-/** A capability's calls for one session: those of api.ts, with the session already chosen. */
+import type { AgentBackendInfo, AgentBackgroundTasks, AgentInput, AgentInterrupt, AgentMessageQueue, AgentModels, AgentPermissionMode, AgentPermissionModes, AgentPermissionRequest, AgentPermissionResult, AgentQuestionRequest, AgentQuestionResponse, AgentSession, AgentStreamingMessage, SessionRef } from "../api.ts";
+import type { Transcript, TranscriptFiles } from "./fileTranscript.ts";
 export type ForSession<Capability> = {
     [K in keyof Capability]: Capability[K] extends (ref: SessionRef, ...args: infer Args) => infer Result ? (...args: Args) => Result : never;
 };
-/** What one session's CLI runs with. */
 export type SessionLaunch = {
     spec: AgentSession;
-    /** The backend's id for the conversation, from an earlier run, to resume it; null for a new one. */
     nativeId: string | null;
     cwd: string;
-    /** The model chosen through AgentModels; null for the backend's default. */
     model: string | null;
-    /** Where backends are installed (see SessionBackend.install). */
+    permissionMode: AgentPermissionMode;
     installDir: string;
-    /** The worker's own environment, the CLI pointed at its home, and the session's. */
     env: Record<string, string>;
 };
-/** What the CLI reports to, and asks of, the worker. */
 export type SessionCallbacks = {
-    /** Appends to the session's stream. */
     emit(message: AgentStreamingMessage): void;
-    /** Records the backend's conversation id, so a later run can resume it. */
     setNativeId(id: string): void;
-    /** The decision on a tool call: someone's answer, or a denial once the turn is interrupted, the session stops, or `signal` aborts. */
     requestPermission(request: Omit<AgentPermissionRequest, "id">, signal?: AbortSignal): Promise<AgentPermissionResult>;
-    /** The user's answers, or null once the turn is interrupted, the session stops, or `signal` aborts. */
     askQuestions(request: Omit<AgentQuestionRequest, "id">, signal?: AbortSignal): Promise<AgentQuestionResponse | null>;
-    /** The CLI is gone (crashed, or closed); the next message starts it again. */
-    exited(error?: Error): void;
+    exited(exit: CliExit | null, error?: Error): void;
+    activeChanged(): void;
+    subagentStarted(toolUseId: string, subagentId: string): void;
+};
+export type CliExit = {
+    code: number | null;
+    signal: string | null;
 };
 export type SessionContext = SessionLaunch & SessionCallbacks;
-/** One session's running CLI: the capabilities it serves itself. */
-export type RunningSession = ForSession<AgentInput & AgentInterrupt & AgentSessionStatus & AgentMessageQueue & AgentModels & AgentBackgroundTasks> & {
+export type RunningSession = ForSession<AgentInput & AgentInterrupt & AgentMessageQueue & AgentModels & AgentPermissionModes & AgentBackgroundTasks> & {
+    active(): boolean;
     close(): Promise<void>;
 };
-/** What a CLI's sign-in commands run with. */
 export type AuthEnvironment = {
     installDir: string;
     env: Record<string, string>;
     cwd: string;
 };
-/** A sign-in in progress: the CLI's own login command. */
 export interface LoginProcess {
-    /** Resolves once the CLI has shown where to sign in. */
     prompt: Promise<{
         url: string;
         userCode?: string;
         needsCode: boolean;
     }>;
-    /** Resolves when the CLI signed in; rejects with why it didn't. */
     done: Promise<void>;
-    /** Gives the CLI the code the sign-in page showed. */
     submitCode(code: string): void;
     cancel(): void;
 }
-/** A CLI's sign-in, through its own commands. The credentials it saves are fakes when a gateway holds the real ones. */
 export type BackendAuth = {
     signedIn(environment: AuthEnvironment): Promise<boolean>;
-    /** With `gatewaySignedIn` (the dimension's gateway holds the upstream's credential) it completes by itself: the gateway answers. */
     login(environment: AuthEnvironment, gatewaySignedIn: boolean): LoginProcess;
 };
-/** What finds a session's conversation in its backend's storage, read through `files`. */
 export type TranscriptSource = {
     nativeId: string;
     env: Record<string, string>;
     files: TranscriptFiles;
+    installDir: string;
 };
-/** An agent CLI, wired in agent/session/<backend>/: one file per capability. */
 export type SessionBackend = {
-    /** Installs the backend under `installDir`, or updates it to the pinned version. Runs in the dimension. */
     install(installDir: string): Promise<void>;
-    /** What's installed under `installDir`, and whether it's what install leaves: this release's version, complete. */
-    installed(installDir: string): Promise<Pick<AgentBackendInfo, "version" | "ready">>;
+    installed(installDir: string): Promise<Omit<AgentBackendInfo, "backend">>;
     start(context: SessionContext): Promise<RunningSession>;
     auth: BackendAuth;
-    /** The conversation `nativeId` in the backend's own storage, which needs no CLI running. */
-    transcript(source: TranscriptSource): FileTranscript;
-    /** The environment that points the CLI at `home` for everything it keeps (see SessionStorage.backendHome). */
+    transcript(source: TranscriptSource): Transcript;
+    findSubagent(source: TranscriptSource, toolUseId: string): Promise<string | null>;
+    subagentTranscript(source: TranscriptSource, subagentId: string, toolUseId: string): Transcript;
     homeEnvironment(home: string): Record<string, string>;
 };

package/dist/agent/session/claude/home.d.ts

@@ -1,2 +1 @@
-/** Points claude at `home` for everything it keeps: its .claude.json too, which otherwise sits in the home directory. */
 export declare function claudeHomeEnvironment(home: string): Record<string, string>;

package/dist/agent/session/claude/home.js

@@ -1,4 +1,3 @@
-/** Points claude at `home` for everything it keeps: its .claude.json too, which otherwise sits in the home directory. */
 export function claudeHomeEnvironment(home) {
     return { CLAUDE_CONFIG_DIR: home };
 }

package/dist/agent/session/claude/provision.d.ts

@@ -0,0 +1,10 @@
+import type { AgentBackendInfo } from "../../api.ts";
+export declare const CLAUDE_SDK_PACKAGE = "../../../vendor-types/claude/agent-sdk/sdk.js";
+export declare function claudePackage(): {
+    pkg: string;
+    version: string;
+    executables: string;
+};
+export declare function installClaude(installDir: string): Promise<void>;
+export declare function installedClaude(installDir: string): Promise<Omit<AgentBackendInfo, "backend">>;
+export declare function claudeExecutable(installDir: string): string;