@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/sandbox/sandbox-config.ts

@@ -0,0 +1,87 @@
+import * as path from "path";
+import type { SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+import { normalizeGalaxyUrl } from "../profiles";
+import { WORKSPACE_STATE_DIR_NAMES } from "../workspace-state-dir";
+
+/**
+ * Inputs for deriving the OS-sandbox profile. Pure: no I/O, fully testable.
+ * Home-relative credential paths are passed to ASRT as `~/...` literals (it
+ * expands them); cwd/tmp are absolute.
+ */
+export interface SandboxConfigInput {
+  /** Session working directory -- the workspace. */
+  cwd: string;
+  /** OS temp dir (os.tmpdir()). */
+  tmpDir: string;
+  /** Extra silent-write roots (guardian.extraWorkspaceRoots). */
+  extraWriteRoots?: string[];
+  /** Galaxy base URL, if known -- its host is allowlisted for bash network. */
+  galaxyUrl?: string;
+  /** Additional domains a deployment wants reachable from bash. */
+  extraAllowedDomains?: string[];
+}
+
+// Credential/secret locations under $HOME the sandbox blocks bash from reading,
+// mirroring the exec-guard's sensitive-read set. ASRT expands the `~`.
+const DENY_READ = [
+  "~/.ssh",
+  "~/.aws",
+  "~/.gnupg",
+  "~/.config/gcloud",
+  "~/.kube",
+  "~/.docker",
+  "~/Library/Keychains",
+  "~/.netrc",
+  "~/.pgpass",
+  "~/.npmrc",
+  "~/.loom/config.json",
+  "~/.orbit/config.json",
+];
+
+// Sensitive files the sandbox blocks bash from writing even inside the
+// workspace (a project `.env` or a stray key).
+const DENY_WRITE = [".env", ".env.*", "*.pem", "*.key"];
+
+export function hostFromUrl(url?: string): string | undefined {
+  if (!url) return undefined;
+  try {
+    // Normalize via the same helper /connect and the profile system use, so a
+    // scheme-less GALAXY_URL ("usegalaxy.org") still resolves to a host.
+    const parsed = new URL(normalizeGalaxyUrl(url));
+    // Galaxy speaks http(s) only (validateGalaxyUrl enforces this on connect),
+    // so keep the host only for those schemes -- an ftp:// or file:// GALAXY_URL
+    // must not seed the bash network allowlist.
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return undefined;
+    return parsed.hostname || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Build the ASRT profile: writable = workspace + tmp + both state-dir spellings
+ * (ASRT itself refuses an allow path that symlinks out of bounds); readable = everything except the credential set; network
+ * = deny-all for bash by default, allowlisting only the Galaxy host (Galaxy work
+ * itself flows over MCP, not bash, so a tight bash network default is safe).
+ */
+export function buildSandboxConfig(input: SandboxConfigInput): SandboxRuntimeConfig {
+  const allowWrite = [
+    input.cwd,
+    input.tmpDir,
+    ...WORKSPACE_STATE_DIR_NAMES.map((name) => path.join(input.cwd, name)),
+    ...(input.extraWriteRoots ?? []),
+  ];
+  const galaxyHost = hostFromUrl(input.galaxyUrl);
+  const allowedDomains = [
+    ...(galaxyHost ? [galaxyHost] : []),
+    ...(input.extraAllowedDomains ?? []),
+  ];
+  return {
+    network: { allowedDomains, deniedDomains: [] },
+    filesystem: {
+      denyRead: [...DENY_READ],
+      allowWrite,
+      denyWrite: [...DENY_WRITE],
+    },
+  };
+}

package/extensions/orbit/sandbox/sandbox-init-message.ts

@@ -0,0 +1,28 @@
+/**
+ * apt package names that provide the Linux sandbox runtime binaries ASRT shells
+ * out to: `ripgrep` -> rg, `socat` -> socat, `bubblewrap` -> bwrap. These ship as
+ * deb `recommends` (see app/forge.config.ts), so a `--no-install-recommends`
+ * install -- or a distro/derivative that strips Recommends -- can still be missing
+ * them and trip the init failure in issue #305. (#305 only named rg + socat, but
+ * ASRT requires bwrap on Linux too.)
+ */
+export const LINUX_SANDBOX_APT_PACKAGES = ["ripgrep", "socat", "bubblewrap"];
+
+/**
+ * User-facing message for a failed bash-sandbox init. On Linux, when ASRT reports
+ * its runtime prerequisites are missing, append the exact apt install line so the
+ * user can fix it in one step instead of decoding "ripgrep (rg) not found". Pure:
+ * takes the platform and the underlying error message, does no IO.
+ */
+export function describeSandboxInitFailure(
+  platform: NodeJS.Platform,
+  errorMessage: string,
+): string {
+  const base = `Bash sandbox init failed (${errorMessage}); bash stays gated per action.`;
+  // ASRT's initialize() throws "Sandbox dependencies not available: ..." only when
+  // the Linux binary checks fail; anchor on that so unrelated failures stay terse.
+  if (platform === "linux" && /dependencies not available/i.test(errorMessage)) {
+    return `${base} On Debian/Ubuntu, install the prerequisites with: sudo apt install ${LINUX_SANDBOX_APT_PACKAGES.join(" ")}`;
+  }
+  return base;
+}

package/extensions/orbit/secret-redaction.ts

@@ -0,0 +1,247 @@
+/**
+ * Secret redaction for tool OUTPUT (#183).
+ *
+ * The exec-guard decides whether a path may be read; this is the data-shaped
+ * companion that ensures a known secret VALUE never rides a tool result back
+ * into the model's context (and from there into the provider's request logs).
+ * It is value-based by design: we redact the concrete keys Orbit holds -- the
+ * provider/Galaxy API keys in ~/.orbit/config.json and the secret-valued env
+ * vars the agent process carries -- so there are no false positives on ordinary
+ * output. It is a defense-in-depth backstop for the guard, and it also catches
+ * vectors the guard can't (an `env` dump, a key pasted into some other file).
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../../shared/orbit-config.js";
+import type { OrbitConfig } from "../../shared/orbit-config.js";
+import { installedConfigSource } from "../../shared/config-source.js";
+import { piAgentDir } from "./agent-dir";
+import { galaxyCredentials } from "./galaxy-api";
+
+export const REDACTED = "[redacted]";
+
+// Below this length a "secret" is too short to redact safely -- scrubbing a
+// 3-char value would mangle ordinary output. Real API keys are far longer.
+const MIN_SECRET_LEN = 8;
+
+// Env vars whose VALUE is a live secret. The agent process carries these at
+// runtime (the CLI exports the active provider's key from config; Orbit injects
+// the decrypted key when it spawns the brain), so an `env`/`printenv` dump would
+// otherwise leak them even when the config file itself is locked down. Only
+// secret-VALUED vars belong here -- not names like AWS_PROFILE. Every LOOM_ name
+// is paired with its ORBIT_ twin (tests/orbit-env-security.test.ts enforces it):
+// either spelling can carry the value, and brain-env forwards both prefixes.
+export const SECRET_ENV_VARS = [
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_OAUTH_TOKEN",
+  "OPENAI_API_KEY",
+  "GEMINI_API_KEY",
+  "GOOGLE_API_KEY",
+  "GROQ_API_KEY",
+  "MISTRAL_API_KEY",
+  "XAI_API_KEY",
+  "DEEPSEEK_API_KEY",
+  "OPENROUTER_API_KEY",
+  "CEREBRAS_API_KEY",
+  "AI_GATEWAY_API_KEY",
+  "AZURE_OPENAI_API_KEY",
+  "HF_TOKEN",
+  "GALAXY_API_KEY",
+  // Custom OpenAI-compatible endpoints carry their key here (pi --api-key). With
+  // the dev/CI env fallback this can be the only place the key lives, so its
+  // value would otherwise dodge redaction.
+  "LOOM_ACTIVE_LLM_API_KEY",
+  "ORBIT_ACTIVE_LLM_API_KEY",
+  // Shell-side secrets that still ride into the brain through the LOOM_/ORBIT_
+  // prefix forwarding, so an `env` dump would otherwise show them.
+  "LOOM_WEB_TOKEN",
+  "ORBIT_WEB_TOKEN",
+  "LOOM_FEEDBACK_KEY",
+  "ORBIT_FEEDBACK_KEY",
+];
+
+// Keys in a stored pi credential that are metadata rather than secret. Every
+// other long-enough string in the entry gets collected, deliberately: pi-ai's
+// OAuthCredentials carries an open index signature (`[key: string]: unknown`),
+// so a provider can add a token-shaped field whenever it likes. The two failure
+// modes are not symmetric -- missing a field leaks a live token, over-matching
+// costs a `[redacted]` where an account id used to print -- so this errs toward
+// collecting.
+const AUTH_METADATA_KEYS = new Set(["type", "expires"]);
+
+/**
+ * Read pi's credential store (~/.pi/agent/auth.json, or wherever
+ * PI_CODING_AGENT_DIR points). Best-effort: absent, unreadable, or mid-write
+ * under pi's lock all yield null and simply contribute no secrets, exactly as
+ * an unconfigured provider does. Never throws -- a redaction pass that failed
+ * closed would drop every tool result.
+ */
+export function loadPiAuth(agentDir: string = piAgentDir()): unknown {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(agentDir, "auth.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Minimal structural shape for a pi tool-result content item. */
+interface ContentItem {
+  type: string;
+  text?: string;
+}
+
+/**
+ * Gather the concrete secret strings to scrub: every API key in the config
+ * (plaintext apiKey AND the apiKeyEncrypted blob, for LLM providers and Galaxy
+ * profiles) plus the known secret-valued env vars. Pure -- env is passed in so
+ * it's testable. `testerId` is deliberately not a secret, so it survives (the
+ * #189 path can read it without leaking keys). `extra` is for values a caller
+ * already holds that live in none of those places.
+ */
+export function collectSecretValues(
+  config: OrbitConfig,
+  env: Record<string, string | undefined>,
+  auth: unknown = null,
+  extra: readonly unknown[] = [],
+): string[] {
+  const out = new Set<string>();
+  const add = (v: unknown): void => {
+    if (typeof v === "string" && v.length >= MIN_SECRET_LEN) out.add(v);
+  };
+  for (const p of Object.values(config.llm?.providers ?? {})) {
+    add(p?.apiKey);
+    add(p?.apiKeyEncrypted);
+  }
+  for (const p of Object.values(config.galaxy?.profiles ?? {})) {
+    add(p?.apiKey);
+    add(p?.apiKeyEncrypted);
+  }
+  for (const name of SECRET_ENV_VARS) add(env[name]);
+  // pi's auth.json: the one credential class Orbit cannot encrypt at rest, so
+  // value-redaction is the only backstop its tokens get.
+  for (const cred of Object.values((auth ?? {}) as Record<string, unknown>)) {
+    if (!cred || typeof cred !== "object") continue;
+    for (const [key, value] of Object.entries(cred as Record<string, unknown>)) {
+      if (AUTH_METADATA_KEYS.has(key)) continue;
+      if (typeof value === "string") add(value);
+      // An api-key credential nests provider-scoped config under `env`
+      // (Cloudflare account/gateway ids and the like), which can itself be secret.
+      else if (value && typeof value === "object")
+        for (const nested of Object.values(value as Record<string, unknown>)) add(nested);
+    }
+  }
+  for (const v of extra) add(v);
+  return [...out];
+}
+
+/**
+ * Everything the redactor scrubs right now: the config's keys, the secret env
+ * vars, pi's auth.json where pi runs natively, the Galaxy key the transport
+ * holds, and whatever the shell's config source lists. `auth: false` leaves
+ * auth.json out: only the tool_result redactor has ever read it, and the
+ * activity log and lesson text keep the set they had.
+ */
+export function currentSecretValues({ auth = true }: { auth?: boolean } = {}): string[] {
+  const source = installedConfigSource();
+  // A shell that hands over the config hands over its secrets too; auth.json is pi's own store.
+  const piAuth = auth && !source ? loadPiAuth() : null;
+  return collectSecretValues(loadConfig(), process.env, piAuth, [
+    galaxyCredentials().apiKey,
+    ...(source?.secrets?.() ?? []),
+  ]);
+}
+
+/**
+ * Replace every occurrence of each known secret with the placeholder. Literal
+ * (no regex, so key characters can't be misread as patterns); longest-first so a
+ * key that contains a shorter one is scrubbed whole. Short/empty values ignored.
+ */
+export function redactSecrets(text: string, secrets: Iterable<string>): string {
+  let out = text;
+  const sorted = [...secrets]
+    .filter((s) => s.length >= MIN_SECRET_LEN)
+    .sort((a, b) => b.length - a.length);
+  for (const s of sorted) {
+    if (out.includes(s)) out = out.split(s).join(REDACTED);
+  }
+  return out;
+}
+
+/**
+ * Redact text items of a tool-result content array. Returns a changed copy, or
+ * `null` if nothing matched (so the caller can no-op). Non-text items (images)
+ * pass through untouched; the original array is never mutated.
+ */
+export function redactContent<T extends ContentItem>(content: T[], secrets: string[]): T[] | null {
+  if (secrets.length === 0) return null;
+  let changed = false;
+  const next = content.map((c) => {
+    if (c && c.type === "text" && typeof c.text === "string") {
+      const red = redactSecrets(c.text, secrets);
+      if (red !== c.text) {
+        changed = true;
+        return { ...c, text: red };
+      }
+    }
+    return c;
+  });
+  return changed ? next : null;
+}
+
+/**
+ * Register the output-redaction hook. Runs after every tool and rewrites the
+ * result content the model receives, so a leaked key never reaches the provider.
+ * Reloads config each time so a key added mid-session is covered immediately;
+ * a clean result returns nothing (pi keeps the original).
+ */
+export function registerSecretRedaction(pi: ExtensionAPI): void {
+  pi.on("tool_result", async (event) => {
+    const secrets = currentSecretValues();
+    const content = redactContent(event.content, secrets);
+    // An in-process Galaxy result keeps its whole envelope here, and codemode hands it to the
+    // model's script; a spilled one previews only part of it in `content`.
+    const structured = event.structuredContent;
+    const scrubbed = structured === undefined ? undefined : redactValue(structured, secrets);
+    if (!content && scrubbed === structured) return;
+    return {
+      ...(content ? { content } : {}),
+      ...(scrubbed === undefined ? {} : { structuredContent: scrubbed }),
+    };
+  });
+}
+
+/** `value` with every string redacted, or `value` itself when nothing matched. */
+function redactValue<T>(value: T, secrets: string[]): T {
+  if (secrets.length === 0) return value;
+  if (typeof value === "string") return redactSecrets(value, secrets) as T;
+  if (Array.isArray(value)) {
+    const next = value.map((v) => redactValue(v, secrets));
+    return next.some((v, i) => v !== value[i]) ? (next as T) : value;
+  }
+  if (value && typeof value === "object") {
+    // What reaches the model is the serialized form, which an object's toJSON decides.
+    if (typeof (value as { toJSON?: unknown }).toJSON === "function") {
+      let plain: unknown;
+      try {
+        plain = JSON.parse(JSON.stringify(value));
+      } catch {
+        return value;
+      }
+      const r = redactValue(plain, secrets);
+      return r !== plain ? (r as T) : value;
+    }
+    let changed = false;
+    const next = Object.fromEntries(
+      Object.entries(value).map(([k, v]) => {
+        const key = redactSecrets(k, secrets);
+        const r = redactValue(v, secrets);
+        if (r !== v || key !== k) changed = true;
+        return [key, r];
+      }),
+    );
+    return changed ? (next as T) : value;
+  }
+  return value;
+}

package/extensions/orbit/session-index/cwd.ts

@@ -0,0 +1,18 @@
+/**
+ * Pi.dev encodes each working directory as "--<path-with-slashes-as-dashes>--"
+ * and uses that as the per-cwd session directory name under ~/.pi/agent/sessions/.
+ *
+ * Lossy by design -- a cwd with a literal hyphen collides with one where a
+ * slash sat in the same position. This matches Pi's own on-disk encoding
+ * (see Pi's SessionManager.getDefaultSessionDir). Do not add escaping; the
+ * indexer needs to reproduce the exact directory name Pi writes.
+ */
+export function encodeCwd(cwd: string): string {
+  return `--${cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+}
+
+export function decodeCwd(encoded: string): string | null {
+  if (!encoded.startsWith("--") || !encoded.endsWith("--")) return null;
+  const inner = encoded.slice(2, -2);
+  return "/" + inner.replace(/-/g, "/");
+}

package/extensions/orbit/session-index/db.ts

@@ -0,0 +1,56 @@
+import Database, { type Database as Db } from "better-sqlite3";
+import fs from "node:fs";
+import path from "node:path";
+import { SCHEMA_SQL, SCHEMA_VERSION } from "./schema";
+import { resolveStateDir } from "../../../shared/state-dir.js";
+
+export { SCHEMA_VERSION };
+
+/**
+ * Open (and if needed rebuild) the session-index database.
+ *
+ * The index is a derived cache -- Pi's JSONL files are the source of truth --
+ * so a schema-version mismatch triggers a clean rebuild rather than a
+ * migration. Cheap because the next scan will repopulate.
+ */
+export function openIndexDb(filePath: string): Db {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  let db = new Database(filePath);
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+
+  const existing = isSchemaCurrent(db);
+  if (!existing) {
+    // Single-writer assumption: the session-index DB has one owner per user.
+    // If a second process opens between close() and the rmSync calls, its
+    // handle becomes invalid -- accepted tradeoff for a derived-cache layer.
+    db.close();
+    fs.rmSync(filePath, { force: true });
+    fs.rmSync(filePath + "-wal", { force: true });
+    fs.rmSync(filePath + "-shm", { force: true });
+    db = new Database(filePath);
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    db.exec(SCHEMA_SQL);
+    db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?)").run(
+      String(SCHEMA_VERSION),
+    );
+  }
+  return db;
+}
+
+function isSchemaCurrent(db: Db): boolean {
+  try {
+    const row = db.prepare("SELECT value FROM meta WHERE key='schema_version'").get() as
+      { value: string } | undefined;
+    return row?.value === String(SCHEMA_VERSION);
+  } catch {
+    // meta table doesn't exist yet
+    return false;
+  }
+}
+
+/** Default location: <state dir>/sessions-index.db. */
+export function defaultDbPath(): string {
+  return path.join(resolveStateDir(), "sessions-index.db");
+}

package/extensions/orbit/session-index/indexer.ts

@@ -0,0 +1,154 @@
+import type { Database as Db } from "better-sqlite3";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parseSessionFile, type EntryRow, type ToolCallRow } from "./parse";
+import { decodeCwd } from "./cwd";
+
+export interface ScanReport {
+  sessionsSeen: number;
+  sessionsRemoved: number;
+  entriesInserted: number;
+  toolCallsInserted: number;
+}
+
+/**
+ * Default location of Pi's session corpus.
+ */
+export function defaultSessionsDir(): string {
+  return path.join(os.homedir(), ".pi", "agent", "sessions");
+}
+
+/**
+ * Incrementally synchronize the index DB against a sessions directory.
+ *
+ * Safe to call repeatedly. On the first call, indexes every file in bulk.
+ * Subsequent calls resume per-file from the stored byte offset; files
+ * whose mtime hasn't advanced are skipped. Sessions whose file has been
+ * deleted are removed from the index.
+ */
+export function scanSessions(db: Db, sessionsDir: string = defaultSessionsDir()): ScanReport {
+  const report: ScanReport = {
+    sessionsSeen: 0,
+    sessionsRemoved: 0,
+    entriesInserted: 0,
+    toolCallsInserted: 0,
+  };
+
+  if (!fs.existsSync(sessionsDir)) return report;
+
+  const knownFiles = listJsonlFiles(sessionsDir);
+  const seenPaths = new Set(knownFiles);
+
+  // Stale-session cleanup (ON DELETE CASCADE handles entries + tool_calls)
+  const existing = db.prepare("SELECT session_id, file_path FROM sessions").all() as Array<{
+    session_id: string;
+    file_path: string;
+  }>;
+  const del = db.prepare("DELETE FROM sessions WHERE session_id = ?");
+  for (const row of existing) {
+    if (!seenPaths.has(row.file_path)) {
+      del.run(row.session_id);
+      report.sessionsRemoved++;
+    }
+  }
+
+  const selState = db.prepare(
+    "SELECT session_id, last_indexed_offset FROM sessions WHERE file_path = ?",
+  );
+  const upsertSession = db.prepare(`
+    INSERT INTO sessions(
+      session_id, file_path, cwd, name, parent_session, notebook_path,
+      created_at, last_indexed_at, last_indexed_offset
+    )
+    VALUES (@session_id, @file_path, @cwd, @name, @parent_session, @notebook_path,
+            @created_at, @last_indexed_at, @last_indexed_offset)
+    ON CONFLICT(session_id) DO UPDATE SET
+      name            = COALESCE(excluded.name, sessions.name),
+      notebook_path   = COALESCE(excluded.notebook_path, sessions.notebook_path),
+      last_indexed_at = excluded.last_indexed_at,
+      last_indexed_offset = excluded.last_indexed_offset
+  `);
+  const insEntry = db.prepare(`
+    INSERT OR IGNORE INTO entries(
+      entry_id, session_id, parent_id, entry_type, timestamp, role, text_content, raw_json
+    ) VALUES (@entry_id, @session_id, @parent_id, @entry_type, @timestamp, @role, @text_content, @raw_json)
+  `);
+  const insTc = db.prepare(`
+    INSERT OR IGNORE INTO tool_calls(entry_id, session_id, tool_use_id, tool_name, arguments_json, result_text)
+    VALUES (@entry_id, @session_id, @tool_use_id, @tool_name, @arguments_json, @result_text)
+  `);
+
+  const indexOne = db.transaction((filePath: string) => {
+    const prior = selState.get(filePath) as
+      { session_id: string; last_indexed_offset: number } | undefined;
+    const startOffset = prior?.last_indexed_offset ?? 0;
+    const fileSize = fs.statSync(filePath).size;
+    if (prior && startOffset >= fileSize) return;
+
+    const parsed = parseSessionFile(filePath, {
+      startOffset,
+      skipHeader: startOffset > 0,
+    });
+
+    // Decode cwd from directory name (fallback to header.cwd when decode fails)
+    const enclosingDir = path.basename(path.dirname(filePath));
+    const cwd = decodeCwd(enclosingDir) ?? parsed.header.cwd ?? "";
+
+    const sessionId = prior?.session_id ?? parsed.header.id;
+    if (!sessionId) return;
+
+    upsertSession.run({
+      session_id: sessionId,
+      file_path: filePath,
+      cwd,
+      name: parsed.sessionName,
+      parent_session: parsed.header.parentSession,
+      notebook_path: parsed.notebookPath,
+      created_at: parsed.header.createdAt || new Date().toISOString(),
+      last_indexed_at: new Date().toISOString(),
+      last_indexed_offset: parsed.endOffset,
+    });
+
+    for (const entry of parsed.entries) {
+      const info = insEntry.run({
+        ...entry,
+        session_id: sessionId,
+      } as EntryRow & { session_id: string });
+      if (info.changes > 0) report.entriesInserted++;
+    }
+    for (const tc of parsed.tool_calls) {
+      const info = insTc.run({
+        ...tc,
+        session_id: sessionId,
+      } as ToolCallRow & { session_id: string });
+      if (info.changes > 0) report.toolCallsInserted++;
+    }
+
+    report.sessionsSeen++;
+  });
+
+  for (const fp of knownFiles) {
+    try {
+      indexOne(fp);
+    } catch {
+      // Broken file -- skip, don't halt the scan
+    }
+  }
+
+  return report;
+}
+
+function listJsonlFiles(root: string): string[] {
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const sub = path.join(root, entry.name);
+    for (const file of fs.readdirSync(sub, { withFileTypes: true })) {
+      if (!file.isFile()) continue;
+      if (!file.name.endsWith(".jsonl")) continue;
+      out.push(path.join(sub, file.name));
+    }
+  }
+  return out;
+}

package/extensions/orbit/session-index/is-enabled.ts

@@ -0,0 +1,17 @@
+import { loadConfig } from "../config";
+import { readEnv } from "../../../shared/orbit-env.js";
+
+/**
+ * Whether the experimental session-index tools are opted in.
+ *
+ * Resolution order mirrors isTeamDispatchEnabled():
+ *   1. LOOM_SESSION_INDEX env var -- "1" -> on, "0" -> off, else defer.
+ *   2. config.experiments.sessionIndex -- boolean.
+ *   3. Default: off.
+ */
+export function isSessionIndexEnabled(): boolean {
+  const env = readEnv("SESSION_INDEX");
+  if (env === "1") return true;
+  if (env === "0") return false;
+  return loadConfig().experiments?.sessionIndex === true;
+}