@galaxyproject/orbit 0.0.0 → 0.9.0

package/bin/pi-extension-path.d.ts

@@ -0,0 +1,4 @@
+export function resolvePiExtensionDir(
+  name: string,
+  resolveSpecifier: (specifier: string) => string,
+): string;

package/bin/pi-extension-path.js

@@ -0,0 +1,44 @@
+// Resolve the on-disk directory of a Pi extension package (pi-mcp-adapter,
+// pi-web-access) so bin/orbit.js can hand the path to Pi as an extension.
+//
+// Two package shapes are in the wild and neither resolves the other's way:
+//
+//   * No "exports" map (pi-mcp-adapter <=2.11.0, pi-web-access today). These
+//     also declare no "main", so the bare specifier has nothing to resolve
+//     against -- only the deep "<name>/index.ts" subpath works.
+//   * An "exports" map (pi-mcp-adapter >=2.12.0). Exports are a closed list, so
+//     the deep subpath is refused with ERR_PACKAGE_PATH_NOT_EXPORTED -- only the
+//     bare specifier works, and it points at index.ts anyway.
+//
+// Orbit depends on a range that spans both shapes, so a fresh install resolves to
+// whichever the registry serves today. Hardcoding either specifier breaks the
+// other half. pi-mcp-adapter 2.12.0 added its exports map on 2026-07-24 and that
+// silently broke `npm install -g @galaxyproject/orbit` -- the CLI died on startup
+// before printing anything. Try both and take whichever answers.
+
+import { dirname } from "node:path";
+
+/**
+ * @param {string} name package name, e.g. "pi-mcp-adapter"
+ * @param {(specifier: string) => string} resolveSpecifier normally a
+ *   `createRequire(...)`-derived `require.resolve`; injected so this is testable
+ *   without installing several versions of the real package.
+ * @returns {string} directory containing the extension's entry point
+ */
+export function resolvePiExtensionDir(name, resolveSpecifier) {
+  const failures = [];
+  // Bare first: it honors whatever entry point the package declares. The deep
+  // subpath is the compatibility fallback for packages that declare none.
+  for (const specifier of [name, `${name}/index.ts`]) {
+    try {
+      return dirname(resolveSpecifier(specifier));
+    } catch (err) {
+      failures.push(`  ${specifier} -- ${err && (err.code || err.message)}`);
+    }
+  }
+  throw new Error(
+    `orbit: could not resolve the "${name}" extension. Tried:\n${failures.join("\n")}\n` +
+      `This usually means the package is missing or was published with an entry ` +
+      `point Orbit does not know about. Reinstalling Orbit normally fixes it.`,
+  );
+}

package/bin/provider-auth.d.ts

@@ -0,0 +1,22 @@
+export declare function hasStoredCredential(
+  auth: Record<string, unknown> | undefined,
+  provider: string,
+): boolean;
+
+export declare function isProviderUsable(
+  provider: string,
+  entry: { apiKey?: string } | undefined,
+  auth: Record<string, unknown> | undefined,
+  opts?: {
+    env?: Record<string, string | undefined>;
+    oauthOnlyProviders?: ReadonlySet<string>;
+    providerEnvMap?: Record<string, string>;
+    customKeyResolved?: string | undefined;
+  },
+): boolean;
+
+export declare function pickSignedInFallback(
+  auth: Record<string, unknown> | undefined,
+  oauthOnlyProviders: Iterable<string>,
+  current: string,
+): string | null;

package/bin/provider-auth.js

@@ -0,0 +1,77 @@
+/**
+ * Deciding whether this process can authenticate a given LLM provider, and
+ * which signed-in provider to fall back on when it can't.
+ *
+ * Split out of bin/orbit.js so the decision is testable without spawning the
+ * CLI -- #429 was a wrong answer here that silently rewrote user config.
+ */
+
+/**
+ * Does ~/.pi/agent/auth.json hold a credential pi can use for this provider?
+ *
+ * Checked for EVERY provider, not just sign-in-only ones: pi reads auth.json
+ * natively, so a stored anthropic login is exactly as usable as a codex one.
+ * The old code only consulted auth.json for openai-codex, which meant a CLI
+ * user signed into Anthropic still got judged unusable and bounced elsewhere.
+ */
+export function hasStoredCredential(auth, provider) {
+  const cred = auth?.[provider];
+  if (!cred || typeof cred !== "object" || Array.isArray(cred)) return false;
+  // Mirrors pi's own idea of a valid credential: OAuthCredential requires
+  // access + refresh + expires (a partial entry has nothing to refresh with),
+  // and ReadOnlyAuthStorage.load() hard-throws on anything that isn't one of
+  // these two shapes. Tolerating a looser shape -- a missing `type`, say --
+  // doesn't buy compatibility with older files, it just calls something a login
+  // when nothing downstream can authenticate with it.
+  if (cred.type === "api_key") {
+    const validKey = cred.key === undefined || typeof cred.key === "string";
+    const validEnv =
+      cred.env === undefined ||
+      (typeof cred.env === "object" &&
+        cred.env !== null &&
+        !Array.isArray(cred.env) &&
+        Object.values(cred.env).every((v) => typeof v === "string"));
+    return validKey && validEnv;
+  }
+  return (
+    cred.type === "oauth" &&
+    typeof cred.access === "string" &&
+    typeof cred.refresh === "string" &&
+    typeof cred.expires === "number" &&
+    Number.isFinite(cred.expires)
+  );
+}
+
+/**
+ * Can this process authenticate `provider`?
+ *
+ * `oauthOnlyProviders` is the set that authenticates ONLY by sign-in -- for pi
+ * 0.84 that is just openai-codex. Providers that offer sign-in *and* accept a
+ * key (anthropic, xai, openrouter, ...) are deliberately not in it: they can
+ * still be driven by an API key, which is the whole point of #429.
+ *
+ * `customKeyResolved` is the already-resolved key for an OpenAI-compatible
+ * custom provider, or undefined when the entry isn't one.
+ */
+export function isProviderUsable(provider, entry, auth, opts = {}) {
+  const { env = {}, oauthOnlyProviders = new Set(), providerEnvMap = {}, customKeyResolved } = opts;
+  if (hasStoredCredential(auth, provider)) return true;
+  // Sign-in is the only way in, and there's no stored login -- no key can help.
+  if (oauthOnlyProviders.has(provider)) return false;
+  if (customKeyResolved !== undefined) return Boolean(customKeyResolved);
+  if (entry?.apiKey) return true;
+  const envVar = providerEnvMap[provider];
+  return Boolean(envVar && env[envVar]);
+}
+
+/**
+ * Pick a signed-in sign-in-only provider to fall back to. Returns null when
+ * nothing is signed in, or when the only candidate is the provider we're
+ * already on.
+ */
+export function pickSignedInFallback(auth, oauthOnlyProviders, current) {
+  for (const p of oauthOnlyProviders) {
+    if (p !== current && hasStoredCredential(auth, p)) return p;
+  }
+  return null;
+}

package/bin/thinking-pref.js

@@ -0,0 +1,38 @@
+// Terminal "thinking block" visibility. Pi streams the model's reasoning into
+// the interactive TUI by default, which makes the Orbit terminal noisy. Orbit
+// hides it by default and writes the resolved value to pi's `hideThinkingBlock`
+// setting (the same ~/.pi/agent/settings.json Orbit already manages for
+// `quietStartup`). That setting is global and only the interactive renderer
+// reads it, so bin/orbit.js only reconciles it for interactive terminal launches.
+//
+// Override the default persistently with `ui.showThinking: true` in
+// ~/.orbit/config.json; for a one-off, pi's built-in Ctrl+T toggles it live.
+//
+// Pure so it can be unit-tested; bin/orbit.js supplies the config value.
+
+/**
+ * Resolve whether pi should hide thinking blocks in the terminal.
+ * @param {{ configShowThinking?: boolean }} [opts] `ui.showThinking` from ~/.orbit/config.json
+ * @returns {boolean} true = hide (the default); false = show (config opted in)
+ */
+export function resolveHideThinking({ configShowThinking } = {}) {
+  return configShowThinking !== true;
+}
+
+/**
+ * Is this Orbit launch an interactive terminal TUI? `hideThinkingBlock` only
+ * affects pi's interactive renderer, so non-interactive launches must not
+ * write it (it would churn the global settings file for a setting they never
+ * read): `--mode rpc` (Orbit and the web dev server), `--mode json` (evals),
+ * and headless `--print` / `-p`. Gating on the mode rather than a per-spawner
+ * env var means new non-interactive callers are covered automatically.
+ * @param {string[]} [argv] the CLI user args (process.argv.slice(2))
+ * @returns {boolean}
+ */
+export function isInteractiveTerminal(argv = []) {
+  if (argv.includes("--print") || argv.includes("-p")) return false;
+  const i = argv.indexOf("--mode");
+  const mode =
+    i !== -1 ? argv[i + 1] : argv.find((a) => a.startsWith("--mode="))?.slice("--mode=".length);
+  return mode !== "rpc" && mode !== "json";
+}

package/bin/update-check.d.ts

@@ -0,0 +1,15 @@
+// Mirrors the discriminated union in update-check.js: a failure entry carries
+// no latest/channel; a success entry requires both.
+export type Cache =
+  | { fetchedAt: number; failed: true }
+  | { fetchedAt: number; failed?: false; latest: string; channel: string };
+export function getOrbitVersion(): string;
+export function parseCache(raw: string, now: number): Cache | null;
+export function noticeFor(current: string, cache: Cache | null): string | null;
+export function readCache(): Cache | null;
+export function readNotice(): string | null;
+export function refreshCache(): Promise<void>;
+export function detectInstall(channel: string): {
+  kind: "global" | "local" | "unknown";
+  cmd: string | null;
+};

package/bin/update-check.js

@@ -0,0 +1,137 @@
+// CLI-owned update-check helper. Queries the npm registry for the newest
+// version on the user's channel, caches the answer in the state dir, and exposes a
+// notice string for the CLI-shell glue extension to surface in-session. The
+// network refresh runs as a detached child (see bin/orbit.js) so it never
+// blocks startup or is killed mid-write. Pure helpers (parseCache, noticeFor)
+// are unit-tested; the I/O wrappers are thin.
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+import { isNewer, pickChannel } from "../shared/version-compare.js";
+import { resolveCliVersionCheckPath } from "../shared/state-dir.js";
+
+const PKG = "@galaxyproject/orbit";
+const REGISTRY = "https://registry.npmjs.org/@galaxyproject/orbit";
+const SUCCESS_TTL_MS = 24 * 60 * 60 * 1000;
+const FAILURE_TTL_MS = 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 5000;
+
+// This file lives at <pkg>/bin/update-check.js, so the package root is one up.
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/** @returns {string} the installed Orbit version, from this package's package.json. */
+export function getOrbitVersion() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf-8"));
+  return pkg.version;
+}
+
+/**
+ * @typedef {{ fetchedAt: number, failed: true } | { fetchedAt: number, failed?: false, latest: string, channel: string }} Cache
+ */
+
+/** Parse + TTL-validate a cache file's contents. Pure.
+ * @param {string} raw @param {number} now @returns {Cache | null} */
+export function parseCache(raw, now) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed.fetchedAt !== "number") return null;
+  const failed = parsed.failed === true;
+  if (now - parsed.fetchedAt > (failed ? FAILURE_TTL_MS : SUCCESS_TTL_MS)) return null;
+  if (failed) return { fetchedAt: parsed.fetchedAt, failed: true };
+  if (typeof parsed.latest !== "string" || typeof parsed.channel !== "string") return null;
+  /** @type {Cache} */
+  const entry = { fetchedAt: parsed.fetchedAt, latest: parsed.latest, channel: parsed.channel };
+  return entry;
+}
+
+/** Build the notice string, or null if up to date / no usable cache. Pure.
+ * @param {string} current @param {Cache | null} cache @returns {string | null} */
+export function noticeFor(current, cache) {
+  if (!cache || cache.failed) return null;
+  if (!isNewer(current, cache.latest)) return null;
+  return `orbit ${cache.latest} is available (you have ${current}) -- run: npm i -g ${PKG}@${cache.channel}`;
+}
+
+/** Read + validate the cache from disk. @returns {Cache | null} */
+export function readCache() {
+  try {
+    return parseCache(fs.readFileSync(resolveCliVersionCheckPath(), "utf-8"), Date.now());
+  } catch {
+    return null;
+  }
+}
+
+/** The in-session notice for the current install, or null. @returns {string | null} */
+export function readNotice() {
+  try {
+    return noticeFor(getOrbitVersion(), readCache());
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(entry) {
+  try {
+    const file = resolveCliVersionCheckPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(entry));
+  } catch {}
+}
+
+/** Query the npm registry for the newest version on the install's channel and
+ * cache it. Best-effort: a failure writes a short-TTL failure marker. */
+export async function refreshCache() {
+  if (readCache()) return; // still fresh; nothing to do
+  const channel = pickChannel(getOrbitVersion());
+  try {
+    const res = await fetch(REGISTRY, {
+      headers: { Accept: "application/vnd.npm.install-v1+json" },
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) throw new Error(`registry ${res.status}`);
+    const body = await res.json();
+    // dist-tags is present in the abbreviated install manifest too, so the
+    // lightweight Accept header above is enough -- no full packument needed.
+    const latest = body["dist-tags"]?.[channel];
+    if (typeof latest !== "string") throw new Error("no dist-tag");
+    writeCache({ fetchedAt: Date.now(), latest, channel });
+  } catch {
+    writeCache({ fetchedAt: Date.now(), failed: true });
+  }
+}
+
+/** Resolve how Orbit was installed, for `orbit update`.
+ * @param {string} channel @returns {{ kind: "global" | "local" | "unknown", cmd: string | null }} */
+export function detectInstall(channel) {
+  // A git checkout run via tsx isn't an npm install -- don't try to npm-update it.
+  if (fs.existsSync(path.join(PKG_ROOT, ".git"))) {
+    return { kind: "unknown", cmd: null };
+  }
+  let globalRoot = "";
+  try {
+    globalRoot = execSync("npm root -g", { encoding: "utf-8" }).trim();
+  } catch {}
+  // Compare on a path boundary so "/x/node_modules" doesn't match a sibling
+  // like "/x/node_modules-vendor/...".
+  const isGlobal = Boolean(globalRoot) && PKG_ROOT.startsWith(globalRoot + path.sep);
+  const flag = isGlobal ? "-g " : "";
+  return {
+    kind: isGlobal ? "global" : "local",
+    cmd: `npm install ${flag}${PKG}@${channel}`,
+  };
+}
+
+// Detached-refresh entrypoint: `node bin/update-check.js --refresh`.
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href &&
+  process.argv.includes("--refresh")
+) {
+  refreshCache().finally(() => process.exit(0));
+}

package/extensions/cli-update/index.ts

@@ -0,0 +1,32 @@
+/**
+ * CLI update notice -- terminal-CLI shell glue, NOT part of the loom brain.
+ *
+ * Surfaces the cached "update available" notice (computed by bin/update-check.js)
+ * once per session via ctx.ui.notify. Lives here, alongside orbit-handoff, so
+ * extensions/orbit/ stays shell-neutral. No-ops inside Orbit (which owns its own
+ * updates) and when update checks are disabled.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+// bin/ is a sibling of extensions/; this resolves to <pkg>/bin/update-check.js.
+import { readNotice } from "../../bin/update-check.js";
+import { isDesktopShell, readEnv } from "../../shared/orbit-env.js";
+
+export default function cliUpdateExtension(pi: ExtensionAPI): void {
+  let shown = false;
+  pi.on("before_agent_start", async (_event, ctx: ExtensionContext) => {
+    if (shown) return;
+    shown = true;
+    // Orbit owns updates for its embedded brain; the bundled CLI copy can't be
+    // npm-updated. LOOM_NO_UPDATE_CHECK is set by bin/orbit.js from the config
+    // flag / --no-update-check.
+    if (isDesktopShell()) return;
+    if (readEnv("NO_UPDATE_CHECK") === "1") return;
+    try {
+      const notice = readNotice();
+      if (notice) ctx.ui.notify(notice, "info");
+    } catch {
+      // A notice must never break a session.
+    }
+  });
+}

package/extensions/orbit/activity-hooks.ts

@@ -0,0 +1,141 @@
+/**
+ * Activity hooks — stream user prompts and tool calls into activity.jsonl.
+ *
+ * Mirrors the conversation into the session's append-only activity log so the
+ * Activity pane reflects every non-trivial interaction, not just plan
+ * mutations. Guarded on `getNotebookPath()` so nothing writes before
+ * `initSessionArtifacts()` has set up the session dir.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import * as path from "path";
+import { getNotebookPath } from "./state";
+import { appendActivityEvent } from "./activity";
+import { currentSecretValues, redactSecrets } from "./secret-redaction";
+import { withoutAppendedLessonHints } from "./lessons/pi-event-contract";
+
+// Read-only / filesystem-traversal tools clutter the log without telling the
+// user anything they'd want to re-read later. Omit them. lessons_search is
+// here for a different reason: its query says what the user is stuck on and
+// its result is lesson prose, and the lesson.surfaced row already records
+// which lesson surfaced.
+const NOISY_TOOLS = new Set(["read", "grep", "glob", "ls", "find", "lessons_search"]);
+
+// Tools whose argument shape is known to carry credentials. activity.jsonl
+// lives in the project cwd and users may share the dir (commit it, send it
+// over for help) — never persist secrets there.
+const CREDENTIAL_TOOLS = new Set(["galaxy_set_profile"]);
+
+// Argument keys that universally indicate secrets, redacted on every tool.
+const CREDENTIAL_KEYS = new Set([
+  "apikey",
+  "api_key",
+  "authorization",
+  "token",
+  "password",
+  "secret",
+  "credentials",
+]);
+
+const REDACTED = "[redacted]";
+
+/**
+ * Walk an args object and replace any credential-looking values with a
+ * placeholder. Mutates a deep clone so the live event still has the
+ * original shape (the upstream tool runner needs it).
+ */
+export function redactArgs(toolName: string, args: unknown): unknown {
+  if (CREDENTIAL_TOOLS.has(toolName)) {
+    // Whole-object redact — opt-in for tools that exist solely to take a
+    // credential. Only the tool name survives in the activity log.
+    return { _redacted: true };
+  }
+  if (args === null || typeof args !== "object") return args;
+  if (Array.isArray(args)) return args.map((v) => redactArgs(toolName, v));
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(args as Record<string, unknown>)) {
+    if (CREDENTIAL_KEYS.has(k.toLowerCase())) {
+      out[k] = REDACTED;
+    } else {
+      out[k] = redactArgs(toolName, v);
+    }
+  }
+  return out;
+}
+
+const RESULT_SUMMARY_MAX = 500;
+
+function sessionDir(): string | null {
+  const nb = getNotebookPath();
+  return nb ? path.dirname(nb) : null;
+}
+
+// Redact BEFORE truncating so a secret can't survive by being split across the
+// truncation boundary. Tool RESULTS (unlike args) carry whatever a command
+// printed -- a `cat`-style leak lands here, and this log also feeds /feedback.
+export function summarizeResult(result: unknown, secrets: string[] = []): string {
+  if (result == null) return "";
+  const raw = typeof result === "string" ? result : JSON.stringify(result);
+  const str = redactSecrets(raw, secrets);
+  if (str.length <= RESULT_SUMMARY_MAX) return str;
+  return (
+    str.slice(0, RESULT_SUMMARY_MAX) + `… [truncated ${str.length - RESULT_SUMMARY_MAX} chars]`
+  );
+}
+
+// The end event carries the result after the tool_result hooks, so a lesson
+// hint rides along. It is Orbit's prose, not the tool's output, and this log
+// ships with /feedback; the lesson.surfaced row already says which one fired.
+function withoutHintBlocks(result: unknown): unknown {
+  const content = (result as { content?: unknown } | null)?.content;
+  if (!Array.isArray(content)) return result;
+  return { ...(result as object), content: withoutAppendedLessonHints(content) };
+}
+
+export function registerActivityHooks(pi: ExtensionAPI): void {
+  pi.on("input", async (event) => {
+    const dir = sessionDir();
+    if (!dir) return;
+    appendActivityEvent(dir, {
+      timestamp: new Date().toISOString(),
+      kind: "user.prompt",
+      source: event.source,
+      payload: { text: event.text },
+    });
+    return { action: "continue" };
+  });
+
+  pi.on("tool_execution_start", async (event) => {
+    if (NOISY_TOOLS.has(event.toolName)) return;
+    const dir = sessionDir();
+    if (!dir) return;
+    appendActivityEvent(dir, {
+      timestamp: new Date().toISOString(),
+      kind: "tool.start",
+      source: "agent",
+      payload: {
+        toolCallId: event.toolCallId,
+        toolName: event.toolName,
+        args: redactArgs(event.toolName, event.args),
+      },
+    });
+  });
+
+  pi.on("tool_execution_end", async (event) => {
+    if (NOISY_TOOLS.has(event.toolName)) return;
+    const dir = sessionDir();
+    if (!dir) return;
+    const secrets = currentSecretValues({ auth: false });
+    appendActivityEvent(dir, {
+      timestamp: new Date().toISOString(),
+      kind: "tool.end",
+      source: "agent",
+      payload: {
+        toolCallId: event.toolCallId,
+        toolName: event.toolName,
+        isError: event.isError,
+        resultSummary: summarizeResult(withoutHintBlocks(event.result), secrets),
+      },
+    });
+  });
+}

package/extensions/orbit/activity.ts

@@ -0,0 +1,116 @@
+/**
+ * Activity log — append-only JSONL record of plan/session events.
+ *
+ * Written alongside the session's notebook.md (same dir). Every entry is a
+ * generic envelope {timestamp, kind, source, payload} so new event kinds can
+ * be added without a schema migration. Consumers (activity tab, /summarize)
+ * read back by streaming the file.
+ *
+ * The module also holds an in-memory mirror of the current session's events
+ * so the UI bridge can stream them to the shell without re-parsing JSONL on
+ * every mutation.
+ */
+
+import { appendFileSync, mkdirSync, readFileSync, existsSync } from "fs";
+import * as path from "path";
+import { capabilityProfile } from "../../shared/capability-profile.js";
+
+export interface ActivityEvent {
+  timestamp: string;
+  kind: string;
+  source: string;
+  payload: Record<string, unknown>;
+}
+
+let currentEvents: ActivityEvent[] = [];
+
+type ActivityChangeListener = (events: ActivityEvent[]) => void;
+const changeListeners: ActivityChangeListener[] = [];
+
+/** Subscribe to activity updates; returns an unsubscribe function. */
+export function onActivityChange(listener: ActivityChangeListener): () => void {
+  changeListeners.push(listener);
+  return () => {
+    const idx = changeListeners.indexOf(listener);
+    if (idx >= 0) changeListeners.splice(idx, 1);
+  };
+}
+
+function notifyActivityChange(): void {
+  for (const listener of changeListeners) {
+    listener(currentEvents);
+  }
+}
+
+/** Return a snapshot of the current in-memory event list. */
+export function getActivityEvents(): ActivityEvent[] {
+  return currentEvents;
+}
+
+/** Return the last `n` events (most recent last). Used for context injection. */
+export function getRecentActivityEvents(n: number): ActivityEvent[] {
+  if (n <= 0) return [];
+  return currentEvents.slice(-n);
+}
+
+/** Clear the in-memory event list (session boundary / reset). */
+export function resetActivity(): void {
+  currentEvents = [];
+  notifyActivityChange();
+}
+
+/**
+ * Hydrate the in-memory event list from an existing activity.jsonl on disk.
+ * Called on session_start / notebook-path change so the Activity pane shows
+ * historical events from previous runs.
+ */
+export function loadActivityLog(sessionDir: string): void {
+  const filePath = path.join(sessionDir, "activity.jsonl");
+  currentEvents = [];
+  // A page notebook has no directory beside it, so the mirror starts empty.
+  if (capabilityProfile().notebook !== "file" || !existsSync(filePath)) {
+    notifyActivityChange();
+    return;
+  }
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const event = JSON.parse(line) as ActivityEvent;
+        currentEvents.push(event);
+      } catch {
+        // Skip malformed lines rather than abort the whole session.
+      }
+    }
+  } catch (err) {
+    console.error("activity hydrate failed:", err);
+  }
+  notifyActivityChange();
+}
+
+/**
+ * Append an event to <sessionDir>/activity.jsonl. Creates the directory if
+ * missing. Returns the absolute path of the file that was written, or null
+ * when nothing was written (a page notebook has no file; a failed write).
+ * Also updates the in-memory mirror and notifies listeners so the UI can
+ * refresh incrementally.
+ */
+export function appendActivityEvent(sessionDir: string, event: ActivityEvent): string | null {
+  const filePath = path.join(sessionDir, "activity.jsonl");
+  // The mirror is what the UI bridge and the lesson nudge read; the file is
+  // the audit sidecar, which only a file notebook has a directory for.
+  const onDisk = capabilityProfile().notebook === "file";
+  try {
+    if (onDisk) {
+      mkdirSync(sessionDir, { recursive: true });
+      appendFileSync(filePath, JSON.stringify(event) + "\n", "utf-8");
+    }
+    currentEvents.push(event);
+    notifyActivityChange();
+    return onDisk ? filePath : null;
+  } catch (err) {
+    console.error("activity append failed:", err);
+    return null;
+  }
+}

package/extensions/orbit/agent-dir.ts

@@ -0,0 +1,11 @@
+import * as path from "path";
+import * as os from "os";
+
+/**
+ * Resolve pi's agent directory -- where mcp.json, sessions, and Orbit's own
+ * per-cwd state live. Honors PI_CODING_AGENT_DIR (set in tests and custom
+ * setups), else ~/.pi/agent.
+ */
+export function piAgentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+}