@makerstufferupper/flypi 0.0.0-stage → 0.1.2

package/src/agent/mcp-signin.ts

@@ -0,0 +1,137 @@
+/**
+ * Signing an MCP server in from the settings view (docs/architecture.md Phase 5, risk 5): the half the
+ * status panel left open — a server with an `oauth` entry used to be reported as unreachable, which is true
+ * but not something a user can act on.
+ *
+ * This is pi's own authorization-code flow (PKCE, dynamic client registration or a pre-registered client),
+ * run by pi's `signInMcpServer` — see src/agent/pi-mcp.ts for why flypi calls it directly rather than
+ * through the MCP extension. The only flypi part is the prompt: the authorization URL goes to the browser
+ * as an `mcpAuth` frame, and the address the browser lands on comes back as a paste. That paste is the whole
+ * point — when flypi runs somewhere a browser cannot reach (a box reached over SSH), the loopback callback
+ * pi also listens for never arrives, and the sign-in is otherwise impossible.
+ *
+ * Tokens land in `.flypi/agent/mcp-auth.json`, which is what a conversation's own connections read next time
+ * (src/agent/runtime.ts) and what the status probe sends when it asks a server whether it answers
+ * (src/agent/mcp-status.ts).
+ */
+import type { McpServerEntry } from "@earendil-works/pi-coding-agent";
+import type { FlypiPaths } from "./paths.ts";
+import { loadPiMcpRuntime, mcpCredentials, usesMcpOAuth, type PiMcpOAuthSettings, type PiMcpRuntime } from "./pi-mcp.ts";
+import { readFlypiMcpConfig } from "./runtime.ts";
+
+/**
+ * How long a sign-in may wait for the paste. pi's CLI uses its MCP request timeout for the same wait; this
+ * is longer on purpose — a person opening a URL on a different device, approving it, and copying an address
+ * is slower than a network call, and cancelling a sign-in out from under them is the failure to avoid.
+ */
+export const SIGN_IN_TIMEOUT_MS = 5 * 60_000;
+
+/** One sign-in per server name at a time, process-wide: two flows for one server would race on its tokens. */
+const waiting = new Map<string, (redirectUrl: string | undefined) => void>();
+
+/** Whether a paste would reach a sign-in right now — what the settings view's button is disabled by. */
+export function signInIsWaiting(name: string): boolean {
+	return waiting.has(name);
+}
+
+/**
+ * Hand the pasted address to the sign-in for `name`. Empty cancels. Returns false when nothing is waiting,
+ * which is what the server turns into an error frame rather than a dropped frame.
+ */
+export function submitRedirect(name: string, redirectUrl: string): boolean {
+	const paste = waiting.get(name);
+	if (!paste) return false;
+	paste(redirectUrl.trim() || undefined);
+	return true;
+}
+
+/**
+ * Run the sign-in for one entry of `.flypi/agent/mcp.json`. Resolves once the tokens are stored; throws with
+ * the sentence a reader acts on — the settings view shows whatever comes back.
+ */
+export async function signIn(
+	paths: FlypiPaths,
+	name: string,
+	onAuthorizationUrl: (url: string) => void,
+	timeoutMs = SIGN_IN_TIMEOUT_MS,
+): Promise<void> {
+	const entry = readFlypiMcpConfig(paths).servers.find((server) => server.name === name);
+	if (!entry) throw new Error(`no MCP server named "${name}" in ${paths.mcpPath}`);
+	const target = signInTarget(entry, paths.mcpPath);
+	if ("refusal" in target) throw new Error(target.refusal);
+	if (waiting.has(name)) throw new Error(`a sign-in for "${name}" is already waiting for its redirect URL`);
+
+	// The slot is taken before anything is loaded, so a second click while pi's OAuth machinery is still
+	// arriving is refused too rather than starting a second flow for the same server.
+	let paste: (redirectUrl: string | undefined) => void = () => {};
+	const pasted = new Promise<string | undefined>((resolve) => (paste = resolve));
+	const timer = setTimeout(() => paste(undefined), timeoutMs);
+	timer.unref();
+	waiting.set(name, paste);
+	// Assigned inside the try, so the catch can still name pi's own cancellation error.
+	let pi: PiMcpRuntime | undefined;
+	try {
+		pi = await loadPiMcpRuntime();
+		const credentials = await mcpCredentials(paths);
+		await pi.signInMcpServer({
+			serverUrl: target.url,
+			store: credentials.forServer(name, target.url),
+			settings: oauthSettings(pi.resolveConfigValueOrThrow, entry),
+			prompt: {
+				showAuthorizationUrl: (authorizationUrl) => onAuthorizationUrl(authorizationUrl.href),
+				// pi races this against its own loopback callback, so a browser on this machine finishes the
+				// sign-in without the paste; the paste is what makes it finish when one cannot.
+				promptForRedirectUrl: () => pasted,
+			},
+		});
+	} catch (error) {
+		if (pi && error instanceof pi.McpSignInCancelledError) {
+			throw new Error(`sign-in to "${name}" was cancelled, or no redirect URL arrived within ${Math.round(timeoutMs / 1000)}s`);
+		}
+		throw error;
+	} finally {
+		clearTimeout(timer);
+		waiting.delete(name);
+	}
+}
+
+/**
+ * The URL to authorize against, or the sentence explaining why this entry cannot be signed in to. The rule
+ * is pi's own (src/agent/pi-mcp.ts): an HTTP server authenticates with OAuth when it sends no
+ * `Authorization` header of its own and delegates to no provider — anything else is a credential to fix in
+ * the file, not a sign-in to do.
+ */
+function signInTarget(entry: McpServerEntry, mcpPath: string): { url: string } | { refusal: string } {
+	const config = entry.config;
+	if (!("url" in config)) return { refusal: `"${entry.name}" is a command flypi starts locally: there is nothing to sign in to` };
+	if (config.enabled === false) return { refusal: `"${entry.name}" is disabled in ${mcpPath}` };
+	if (!usesMcpOAuth(config)) {
+		return {
+			refusal: config.auth?.provider
+				? `"${entry.name}" sends the token of provider "${config.auth.provider}" — that is a /login credential, not an OAuth sign-in`
+				: `"${entry.name}" sends its own Authorization header, so it is not an OAuth server — fix that header in ${mcpPath}`,
+		};
+	}
+	return { url: config.url };
+}
+
+/**
+ * The entry's `oauth` block as pi wants it, resolved the way pi resolves it: only `clientSecret` can name an
+ * environment variable or a command, and a reference that does not resolve is an error naming the entry.
+ */
+function oauthSettings(resolve: (value: string, description: string) => string, entry: McpServerEntry): PiMcpOAuthSettings {
+	const oauth = "oauth" in entry.config ? entry.config.oauth : undefined;
+	if (!oauth) return {};
+	return {
+		clientId: oauth.clientId,
+		...(oauth.clientSecret === undefined
+			? {}
+			: { clientSecret: resolve(oauth.clientSecret, `MCP server "${entry.name}" oauth.clientSecret`) }),
+		callbackPort: oauth.callbackPort,
+		callbackUrl: oauth.callbackUrl,
+		scope: oauth.scope,
+		clientName: oauth.clientName,
+		clientRegistration: oauth.clientRegistration,
+		...(oauth.authServerMetadataUrl ? { authServerMetadataUrl: new URL(oauth.authServerMetadataUrl) } : {}),
+	};
+}

package/src/agent/mcp-status.ts

@@ -0,0 +1,168 @@
+/**
+ * The MCP status panel (docs/architecture.md Phase 5): is each server in `.flypi/agent/mcp.json` actually
+ * reachable, how many tools does it offer, what did it complain about.
+ *
+ * pi keeps its own connections inside the MCP extension and shows the host none of that state — not over
+ * the SDK, not in the `.flypi/agent/mcp.log` file it is handed (docs/pi-api.md). So this asks the servers
+ * directly, the way `pi mcp list` does: connect, list tools, close. It is a second set of connections for
+ * as long as the request takes, and it does not touch the ones a running conversation holds — which is the
+ * honest answer to "is it up", since the connections a session made are not the ones this panel describes
+ * after a config edit (an existing conversation keeps its own, docs/architecture.md Phase 5).
+ *
+ * The tool list carries the two annotations that mean something to a reader: `destructiveHint` ("this can
+ * destroy something") and `openWorldHint` ("this reaches outside the machine"). That is what a user puts on
+ * `permissions.askBeforeUse` in src/agent/permission-gate.ts — the gate itself never sees an annotation.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { McpServerEntry } from "@earendil-works/pi-coding-agent";
+import type { FlypiPaths } from "./paths.ts";
+import { mcpCredentials, usesMcpOAuth, type PiMcpCredentials } from "./pi-mcp.ts";
+import { readFlypiMcpConfig } from "./runtime.ts";
+
+/** "not answering" has to be distinguishable from "not up yet", so a probe that hangs is a failure. */
+export type McpServerState = "connected" | "disabled" | "failed" | "needs-auth";
+
+export interface McpToolRow {
+	name: string;
+	/** What the server announced about the tool, not what flypi guessed. Absent means not announced. */
+	destructive: boolean;
+	openWorld: boolean;
+}
+
+export interface McpStatusRow {
+	name: string;
+	state: McpServerState;
+	transport: "http" | "stdio";
+	/** Set for `failed` / `needs-auth`, in the server's own words. */
+	error?: string;
+	tools: McpToolRow[];
+}
+
+export interface McpStatusSnapshot {
+	servers: McpStatusRow[];
+	/** The tail of `.flypi/agent/mcp.log`: pi's own words about the connections a session actually made. */
+	log: string;
+}
+
+/** pi's own startup wait for one server (docs/mcp.md); matching it means this never gives up before pi would. */
+const PROBE_TIMEOUT_MS = 10_000;
+/** The log rotates at 5 MB (pi's MCP extension); the panel shows the end of it, not all of it. */
+const LOG_TAIL_BYTES = 8 * 1024;
+
+/** Every configured server, probed in parallel: one slow one must not add up behind the others. */
+export async function mcpStatus(paths: FlypiPaths, timeoutMs = PROBE_TIMEOUT_MS): Promise<McpStatusSnapshot> {
+	const config = readFlypiMcpConfig(paths);
+	// The OAuth servers need what a sign-in stored (see transportFor), so the probe reads the same file a
+	// conversation's connections read.
+	const credentials = await mcpCredentials(paths);
+	const rows = await Promise.all(config.servers.map((entry) => probe(entry, credentials, timeoutMs)));
+	return { servers: rows, log: mcpLogTail(paths) };
+}
+
+/** Connect and list, then close. Never throws: a server that will not answer is a row, not an error frame. */
+async function probe(entry: McpServerEntry, credentials: PiMcpCredentials, timeoutMs: number): Promise<McpStatusRow> {
+	const config = entry.config;
+	const base = { name: entry.name, transport: "command" in config ? ("stdio" as const) : ("http" as const) };
+	if (config.enabled === false) return { ...base, state: "disabled", tools: [] };
+
+	const client = new Client({ name: "flypi-status", version: "0.0.0" });
+	try {
+		await withTimeout(client.connect(await transportFor(entry, credentials)), timeoutMs);
+		const listed = await withTimeout(client.listTools(), timeoutMs);
+		return {
+			...base,
+			state: "connected",
+			tools: listed.tools.map((tool) => ({
+				name: tool.name,
+				destructive: tool.annotations?.destructiveHint === true,
+				openWorld: tool.annotations?.openWorldHint === true,
+			})),
+		};
+	} catch (error) {
+		// A 401 is its own state: the server is there and the credential is missing or wrong, which is a
+		// different thing to fix than a server that is not up. It is read off the SDK's own status
+		// (`StreamableHTTPError.code`), because the message alone is not enough — a 401 with an empty body
+		// says nothing but "Error POSTing to endpoint".
+		const state: McpServerState = httpStatusOf(error) === 401 ? "needs-auth" : "failed";
+		return { ...base, state, error: (error as Error).message ?? String(error), tools: [] };
+	} finally {
+		await client.close().catch(() => undefined);
+	}
+}
+
+/** The HTTP status of a failed MCP request, or undefined when the failure was not an HTTP answer. */
+function httpStatusOf(error: unknown): number | undefined {
+	const code = (error as { code?: unknown } | null)?.code;
+	return typeof code === "number" ? code : undefined;
+}
+
+/**
+ * The transport pi would build for this entry: URL and headers for HTTP, spawned process for stdio.
+ * `${NAME}` in a header or env value is expanded here because this is a second client and pi's own
+ * expansion does not apply to it — same rule as src/memory/recall.ts.
+ * `shortcut: no "!command" values here either; add them with recall.ts if an entry ever uses one.`
+ */
+async function transportFor(entry: McpServerEntry, credentials: PiMcpCredentials): Promise<Transport> {
+	const config = entry.config;
+	if ("command" in config) {
+		return new StdioClientTransport({
+			command: config.command,
+			args: config.args ?? [],
+			...(config.cwd ? { cwd: config.cwd } : {}),
+			env: { ...getDefaultEnvironment(), ...expand(Object.entries(config.env ?? {})) },
+		});
+	}
+	const headers = expand(Object.entries(config.headers ?? {}));
+	// A server the user signed in to in a browser: send the token that sign-in stored, the way pi's own
+	// connection does. Without it the panel would call a server "needs authorisation" one second after the
+	// sign-in that just worked (docs/architecture.md Phase 5).
+	// shortcut: no refresh here — a token that expired since shows as needs-auth, and signing in again is the fix.
+	const token = usesMcpOAuth(config) ? credentials.tokens(entry.name, config.url)?.access_token : undefined;
+	if (token) headers.Authorization = `Bearer ${token}`;
+	return new StreamableHTTPClientTransport(new URL(config.url), Object.keys(headers).length ? { requestInit: { headers } } : {});
+}
+
+const expand = (entries: [string, string | undefined][]): Record<string, string> =>
+	Object.fromEntries(
+		entries.map(([name, value]) => [name, (value ?? "").replace(/\$\{([A-Za-z0-9_]+)\}/g, (_, env: string) => process.env[env] ?? "")]),
+	);
+
+/** A hung server is the one failure mode that would otherwise leave the panel waiting forever. */
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error(`no answer within ${ms / 1000}s`)), ms);
+		promise.then(
+			(value) => {
+				clearTimeout(timer);
+				resolve(value);
+			},
+			(error) => {
+				clearTimeout(timer);
+				reject(error);
+			},
+		);
+	});
+}
+
+/**
+ * The last `LOG_TAIL_BYTES` of pi's MCP log, whole lines only. Empty when there is no log, which is the
+ * normal state of a machine where nothing has gone wrong; the panel says "nothing logged" rather than
+ * leaving a blank box (risk 8).
+ */
+export function mcpLogTail(paths: FlypiPaths, bytes = LOG_TAIL_BYTES): string {
+	if (!existsSync(paths.mcpLogPath)) return "";
+	let raw: Buffer;
+	try {
+		raw = readFileSync(paths.mcpLogPath);
+	} catch (error) {
+		return `could not read ${paths.mcpLogPath}: ${(error as Error).message}`;
+	}
+	const cut = Math.max(0, raw.length - bytes);
+	const tail = raw.subarray(cut).toString("utf8");
+	// Only when bytes were actually dropped: the first surviving line is then a partial one.
+	return cut > 0 ? tail.replace(/^[^\n]*\n/, "") : tail;
+}

package/src/agent/onboarding.ts

@@ -0,0 +1,74 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** pi's auth.json shape: { "<provider>": { "type": "api_key", "key": "..." } } */
+export type AuthStorage = Record<string, { type: string; key?: string } | undefined>;
+
+export type ResolvedCredential =
+	| { ok: true; provider: string; source: "auth.json" | "models.json" | "env" }
+	| { ok: false; provider: string; message: string };
+
+/** `lmstudio` -> `LMSTUDIO_API_KEY`, `openai` -> `OPENAI_API_KEY`. */
+export function credentialEnvName(provider: string): string {
+	return `${provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_API_KEY`;
+}
+
+function hasValue(value: unknown): boolean {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Decide whether a provider can be used, without throwing: a missing credential is a
+ * message the user can act on, not a stack trace.
+ *
+ * pi's own precedence is auth.json > models.json apiKey > env, so this reports the
+ * source pi would actually use. `env` is listed last because pi reads it last.
+ */
+export function resolveCredential(input: {
+	provider: string;
+	models: { providers?: Record<string, { apiKey?: unknown }> | undefined };
+	auth: AuthStorage;
+	env: Record<string, string | undefined>;
+}): ResolvedCredential {
+	const { provider, models, auth, env } = input;
+	if (hasValue(auth[provider]?.key)) return { ok: true, provider, source: "auth.json" };
+	if (hasValue(models.providers?.[provider]?.apiKey)) return { ok: true, provider, source: "models.json" };
+	if (hasValue(env[credentialEnvName(provider)])) return { ok: true, provider, source: "env" };
+	return {
+		ok: false,
+		provider,
+		message:
+			`no credential for provider "${provider}". Set ${credentialEnvName(provider)} in the environment, ` +
+			`or add {"${provider}":{"type":"api_key","key":"…"}} to the model credential file.`,
+	};
+}
+
+export function readAuth(authPath: string): AuthStorage {
+	if (!existsSync(authPath)) return {};
+	return JSON.parse(readFileSync(authPath, "utf8")) as AuthStorage;
+}
+
+/** Store a key in pi's own credential file (0600), merging unrelated providers. */
+export function writeAuthKey(authPath: string, provider: string, key: string): void {
+	const auth = readAuth(authPath);
+	auth[provider] = { type: "api_key", key };
+	mkdirSync(dirname(authPath), { recursive: true });
+	writeFileSync(authPath, `${JSON.stringify(auth, null, 2)}\n`, { mode: 0o600 });
+	chmodSync(authPath, 0o600);
+}
+
+/**
+ * Move an environment-supplied key into the credential file so later runs (and the
+ * daemon) do not depend on the caller's shell. Returns false when there is nothing to do.
+ */
+export function importEnvCredential(
+	authPath: string,
+	provider: string,
+	env: Record<string, string | undefined>,
+): boolean {
+	const key = env[credentialEnvName(provider)];
+	if (!hasValue(key)) return false;
+	if (hasValue(readAuth(authPath)[provider]?.key)) return false;
+	writeAuthKey(authPath, provider, key as string);
+	return true;
+}

package/src/agent/packages.ts

@@ -0,0 +1,150 @@
+/**
+ * Extension packages — pi's own mechanism (pi's docs/packages.md), pointed at flypi's agent dir so the
+ * settings view can install and update them (docs/protocol.md `packages` / `savePackages`).
+ *
+ * Nothing here reimplements a package: pi's `DefaultPackageManager` owns the source forms (`npm:…`, a git
+ * URL, a path), where the code lands (`<agentDir>/npm/node_modules`, a git checkout, or the path itself),
+ * what counts as an update and how one is reconciled. `agentDir` is `.flypi/agent`, so an installed
+ * extension never reaches the host `~/.pi` (docs/risks.md risk 1) — `assertFlypiOwned` is what guarantees
+ * that, and it runs in `createFlypiSession` before any session loads these packages.
+ *
+ * The declaration lives in `.flypi/agent/settings.json` under `packages`, the same file the settings panel
+ * edits the default model in. pi's `SettingsManager` writes only the field it changed, so a `defaultProvider`
+ * or a `permissions` block survives an install — and it refuses to write at all when that file will not
+ * parse, which is why `applyPackageEdits` checks for a load error before touching anything rather than
+ * reporting an install that never landed.
+ *
+ * **Updates are checked, not fetched, by the panel.** `checkForAvailableUpdates()` reaches the registry and
+ * every git remote, so it runs on the daemon's daily rhythm (src/daemon/index.ts) and its answer is kept in
+ * `.flypi/package-check.json` — the same shape as flypi's own update stamp (src/daemon/update.ts). The panel
+ * reads the stamp; the daemon installs what it found during the same idle stretch it installs flypi with.
+ * A source that names a version (`npm:x@1.2.0`) or a git ref is pinned, and pi leaves pinned sources where
+ * they are: naming a version is asking for that version.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { DefaultPackageManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { FlypiConfigError } from "./runtime.ts";
+import type { FlypiPaths } from "./paths.ts";
+
+/** How long the package answer stays good — the daemon's day, the same rhythm as flypi's own update check. */
+export const PACKAGE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** The answer, next to flypi's own update stamp, so the panel reports it without reaching the network. */
+export const PACKAGE_CHECK_FILE = join(".flypi", "package-check.json");
+
+/** One `packages` entry, as the panel shows it. */
+export interface PackageRow {
+	/** The source exactly as settings.json holds it — `npm:…`, a git URL, or a path. */
+	source: string;
+	/** `project` is an entry in `<root>/.pi/settings.json`; flypi's own edits are always `user`. */
+	scope: "user" | "project";
+	/** Declared, but the code is not on disk. A session would install it on start; the panel says so. */
+	installed: boolean;
+	/** Where the code is: `.flypi/agent/npm/node_modules/<name>`, a checkout, or the local path. */
+	path: string;
+	/** A newer release is published (npm) or the remote moved (git). Only from the daemon's stamp. */
+	update?: boolean;
+}
+
+export interface PackageSnapshot {
+	packages: PackageRow[];
+	/** When the daemon last asked the registries; absent until it has. */
+	checkedAt?: string;
+	/** A `settings.json` pi could not read — said, rather than shown as "no packages". */
+	errors: string[];
+}
+
+export interface PackageEdits {
+	install?: string[];
+	remove?: string[];
+	update?: string[];
+}
+
+/** What the daemon wrote: which sources have an update waiting. */
+export interface PackageCheck {
+	checkedAt: string;
+	/** The `packages` entries, exactly as settings.json holds them. */
+	updates: string[];
+	error?: string;
+}
+
+/** pi's package manager, on flypi's own agent dir, plus the settings file it writes through. */
+function packages(paths: FlypiPaths): { manager: DefaultPackageManager; settings: SettingsManager } {
+	const settings = SettingsManager.create(paths.root, paths.agentDir);
+	return { manager: new DefaultPackageManager({ cwd: paths.root, agentDir: paths.agentDir, settingsManager: settings }), settings };
+}
+
+/** What pi could not read or write, named by file — a settings.json it cannot parse is never silently "empty". */
+function settingsErrors(settings: SettingsManager): string[] {
+	return settings.drainErrors().map((failure) => `${failure.path ?? failure.scope}: ${failure.error.message}`);
+}
+
+/** The list, merged with the daemon's answer. Reaches no network, so the panel can ask on every open. */
+export function readPackages(paths: FlypiPaths): PackageSnapshot {
+	const { manager, settings } = packages(paths);
+	const check = readPackageCheck(paths.root);
+	return {
+		packages: manager.listConfiguredPackages().map((entry) => ({
+			source: entry.source,
+			scope: entry.scope,
+			installed: entry.installedPath !== undefined,
+			path: entry.installedPath ?? "",
+			...(check?.updates.includes(entry.source) ? { update: true } : {}),
+		})),
+		...(check ? { checkedAt: check.checkedAt } : {}),
+		errors: settingsErrors(settings),
+	};
+}
+
+/**
+ * Install, remove or update, then hand back the list as it is now. Applied in order and one at a time:
+ * pi's own npm/git calls are what fail, and a later edit in the same request still runs against what the
+ * earlier ones wrote. A `settings.json` that will not parse is refused up front — pi would install the code
+ * and then decline to record it, which is an install that never lands.
+ */
+export async function applyPackageEdits(paths: FlypiPaths, edits: PackageEdits): Promise<PackageSnapshot> {
+	const { manager, settings } = packages(paths);
+	const unreadable = settingsErrors(settings);
+	if (unreadable.length > 0) throw new FlypiConfigError(unreadable.join("; "));
+	for (const source of edits.install ?? []) await manager.installAndPersist(source);
+	for (const source of edits.remove ?? []) await manager.removeAndPersist(source);
+	for (const source of edits.update ?? []) await manager.update(source);
+	// pi queues settings writes; the file has to be on disk before the snapshot re-reads it.
+	await settings.flush();
+	const errors = settingsErrors(settings);
+	const snapshot = readPackages(paths);
+	return { ...snapshot, errors: [...errors, ...snapshot.errors] };
+}
+
+/**
+ * Ask the registries and remotes which configured sources have something newer. An unreachable registry is
+ * the answer, not a crash — the daemon asks this on a machine that may be offline.
+ */
+export async function checkPackageUpdates(paths: FlypiPaths): Promise<PackageCheck> {
+	const { manager } = packages(paths);
+	try {
+		return { checkedAt: new Date().toISOString(), updates: (await manager.checkForAvailableUpdates()).map((entry) => entry.source) };
+	} catch (error) {
+		return { checkedAt: new Date().toISOString(), updates: [], error: (error as Error).message };
+	}
+}
+
+/** Is the answer too old to trust (or absent)? */
+export function dueForPackageCheck(check: PackageCheck | null, now = Date.now()): boolean {
+	const at = Date.parse(check?.checkedAt ?? "");
+	return Number.isNaN(at) || now - at >= PACKAGE_CHECK_INTERVAL_MS;
+}
+
+export function readPackageCheck(root: string): PackageCheck | null {
+	try {
+		return JSON.parse(readFileSync(join(root, PACKAGE_CHECK_FILE), "utf8")) as PackageCheck;
+	} catch {
+		return null;
+	}
+}
+
+export function writePackageCheck(root: string, check: PackageCheck): void {
+	const file = join(root, PACKAGE_CHECK_FILE);
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, `${JSON.stringify(check, null, 2)}\n`);
+}

package/src/agent/paths.ts

@@ -0,0 +1,80 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+/**
+ * Every path flypi owns lives under `<repo>/.flypi/`. Nothing here may resolve
+ * inside the host `~/.pi` (docs/risks.md risk 1). Pass these to pi explicitly —
+ * never rely on pi's defaults, which do point at `~/.pi/agent`.
+ */
+export interface FlypiPaths {
+	/** Repo root, i.e. the directory containing `.flypi/`. */
+	root: string;
+	/** pi's "agent directory": settings.json, models.json, auth.json, mcp.json. */
+	agentDir: string;
+	/** pi session JSONL files. */
+	sessionsDir: string;
+	/** SQLite memory store (Phase 3) — the memory component's own database. */
+	memoryDir: string;
+	/** The memory database file. Named once so no entrypoint can point at a second one by mistake. */
+	memoryDbPath: string;
+	/** The backend's own database: the run record (Phase 4.5). Never opened by the memory component. */
+	runDbPath: string;
+	/** Embedding-model cache (Phase 3). */
+	modelsDir: string;
+	/** Files pasted into the web UI, which the agent then opens by path (docs/protocol.md). */
+	uploadsDir: string;
+	authPath: string;
+	modelsPath: string;
+	settingsPath: string;
+	mcpPath: string;
+	/** Where pi's MCP extension appends server log messages (`logPath`), and where the status panel reads them back. */
+	mcpLogPath: string;
+	/**
+	 * pi's MCP OAuth state (client registration, access/refresh tokens, the pending PKCE verifier), keyed by
+	 * server name and URL. Named here because pi's default is `<agent-dir>/mcp-auth.json` of *its* agent dir,
+	 * which for flypi would be the host `~/.pi/agent` (risk 1).
+	 */
+	mcpAuthPath: string;
+	/** The vault's key file (docs/secrets.md): mode 0600, created on first use. Never the model keys. */
+	secretKeyPath: string;
+	/** Where `secret_file` writes a plaintext for a command that only takes a path (ssh, gpg). */
+	secretsDir: string;
+}
+
+export function flypiPaths(root: string = process.cwd()): FlypiPaths {
+	const base = resolve(root);
+	const dir = join(base, ".flypi");
+	const agentDir = join(dir, "agent");
+	return {
+		root: base,
+		agentDir,
+		sessionsDir: join(dir, "sessions"),
+		memoryDir: join(dir, "memory"),
+		memoryDbPath: join(dir, "memory", "flypi.db"),
+		runDbPath: join(dir, "backend", "runs.db"),
+		modelsDir: join(dir, "models"),
+		uploadsDir: join(dir, "uploads"),
+		authPath: join(agentDir, "auth.json"),
+		modelsPath: join(agentDir, "models.json"),
+		settingsPath: join(agentDir, "settings.json"),
+		mcpPath: join(agentDir, "mcp.json"),
+		mcpLogPath: join(agentDir, "mcp.log"),
+		mcpAuthPath: join(agentDir, "mcp-auth.json"),
+		secretKeyPath: join(dir, "secret.key"),
+		secretsDir: join(dir, "secrets"),
+	};
+}
+
+/**
+ * The invariant as a runtime check rather than a comment: flypi must never read
+ * or write the host agent dir. Throws with an actionable message.
+ */
+export function assertFlypiOwned(paths: FlypiPaths): void {
+	const host = resolve(join(homedir(), ".pi"));
+	if (paths.root === host || paths.root.startsWith(host + "/")) {
+		throw new Error(`flypi config resolves inside the host pi directory ${paths.root} — move .flypi/ outside ~/.pi`);
+	}
+	if (paths.agentDir !== join(paths.root, ".flypi", "agent")) {
+		throw new Error(`agentDir must be .flypi/agent, got ${paths.agentDir}`);
+	}
+}