pi-session-mcp 0.8.3 → 0.12.0

package/dist/writer-launch.js

@@ -0,0 +1,232 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isEntryPoint } from "./entry-point.js";
+import { serveRefusal } from "./refusal-server.js";
+import { acquireWriterLease, adoptInheritedLease, WriterLeaseError } from "./writer-lease.js";
+import { ensureWriterAbsent, writerContainerName } from "./writer-fence.js";
+import { createProcessRunner } from "./setup-process.js";
+import { ensureWriterEventsDirectory, podmanInfo, serveArgs } from "./writer-boundary.js";
+import { expiresWithin, REFRESH_INTERVAL_MS, REFRESH_THRESHOLD_MINUTES, refreshHostCredential, selectedOAuthProviders, selectBoundaryCredentials, writeBoundaryCredentials } from "./writer-credentials.js";
+import { currentAcceptanceFingerprint, readWriterState, WRITER_NAME_PATTERN, writerEventDeliveryEnabled, writerPaths } from "./writer-state.js";
+export { currentAcceptanceFingerprint } from "./writer-state.js";
+export { renderWrapper, wrapperDigest } from "./writer-wrapper.js";
+export const LAUNCHER_CLEANUP_BOUND_MS = 40_000;
+function launchFailure(stage) {
+    process.stderr.write(JSON.stringify({ level: "error", event: "writer_launch_failed", stage, code: "writer_launch_failed" }) + "\n");
+}
+function eventsFailure() {
+    process.stderr.write(JSON.stringify({ level: "error", event: "writer_launch_failed", stage: "events", code: "events_directory_unavailable" }) + "\n");
+}
+export async function launchEntry(argv, deps) {
+    try {
+        return await launch(argv, deps);
+    }
+    catch {
+        launchFailure("entry");
+        return 1;
+    }
+}
+export async function launch(argv, deps) {
+    const name = argv[0];
+    if (!name || !WRITER_NAME_PATTERN.test(name)) {
+        await serveRefusal("writer_not_ready");
+        return 0;
+    }
+    const inherited = deps.env.PI_WRITER_LEASE_FD;
+    if (inherited !== undefined && (!Number.isSafeInteger(Number(inherited)) || Number(inherited) < 0 || String(Number(inherited)) !== inherited)) {
+        await serveRefusal("writer_not_ready");
+        return 0;
+    }
+    let lease;
+    try {
+        lease = inherited === undefined
+            ? await (deps.lease?.acquire ?? acquireWriterLease)(deps.home, name, { waitMs: 0 })
+            : await (deps.lease?.adopt ?? adoptInheritedLease)(deps.home, name, Number(inherited));
+    }
+    catch (error) {
+        await serveRefusal(error instanceof WriterLeaseError && error.code === "writer_busy" ? "writer_busy" : "writer_not_ready");
+        return 0;
+    }
+    try {
+        return await launchLeased(argv, deps, name, lease);
+    }
+    finally {
+        await lease.release();
+    }
+}
+async function launchLeased(argv, deps, name, lease) {
+    const refuse = async (code) => { await serveRefusal(code); return 0; };
+    const info = await podmanInfo(deps.runner);
+    if (!info.usable || !info.version)
+        return refuse("container_runtime_unavailable");
+    const paths = writerPaths(deps.home, name);
+    let state;
+    try {
+        state = await readWriterState(deps.home, name);
+        if (!state)
+            return refuse("writer_not_ready");
+        if (argv.length === 1) {
+            if (state.phase !== "ready" || state.acceptance?.fingerprint !== await currentAcceptanceFingerprint(paths.wrapper, state, info.version))
+                return refuse("writer_not_ready");
+        }
+    }
+    catch {
+        return refuse("writer_not_ready");
+    }
+    const ensureAbsent = () => (deps.ensureAbsent ?? ensureWriterAbsent)(deps.runner, paths, name, { leaseFd: lease.fd });
+    try {
+        await ensureAbsent();
+    }
+    catch {
+        return refuse("writer_fenced");
+    }
+    let eventsDir;
+    if (state.launch !== "relay" && await writerEventDeliveryEnabled(paths.config)) {
+        try {
+            eventsDir = await ensureWriterEventsDirectory(deps.home, name, (deps.uid ?? (() => process.getuid()))());
+        }
+        catch {
+            eventsFailure();
+            return refuse("writer_not_ready");
+        }
+    }
+    const providers = state.providers;
+    const names = providers.map(({ provider }) => provider);
+    const readHost = async () => {
+        try {
+            return JSON.parse(await readFile(join(deps.home, ".pi", "agent", "auth.json"), "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const refresh = async () => {
+        const host = await readHost();
+        if (expiresWithin(host, names, REFRESH_THRESHOLD_MINUTES, deps.now())) {
+            const warmup = deps.warmupHostCredential ?? refreshHostCredential;
+            const authPath = join(deps.home, ".pi", "agent", "auth.json");
+            // In parallel, so the whole warm-up stays bounded at 20 s; Pi's locked store writes the file, never this launcher.
+            // A failed refresh is ignored: the copy below still runs.
+            await Promise.allSettled(selectedOAuthProviders(host, names).map((provider) => warmup({ authPath, provider, minOAuthValidityMs: REFRESH_THRESHOLD_MINUTES * 60_000, timeoutMs: 20_000 })));
+        }
+        await writeBoundaryCredentials(paths.agent, selectBoundaryCredentials(await readHost(), names));
+    };
+    const enabled = deps.env.PI_WRITER_NO_CREDENTIAL_REFRESH !== "1";
+    try {
+        if (enabled)
+            await refresh();
+    }
+    catch {
+        return refuse("writer_not_ready");
+    }
+    const command = argv.length > 1 ? argv.slice(1) : ["node", "/opt/pi-session-mcp/dist/main.js"];
+    let child;
+    try {
+        child = deps.spawnPodman(serveArgs(paths, state, command, deps.releaseRoot, eventsDir, { name }), [lease.fd]);
+    }
+    catch {
+        launchFailure("spawn");
+        await ensureAbsent();
+        return 1;
+    }
+    let outstanding;
+    let stopping = false;
+    const timer = enabled ? deps.setInterval(() => {
+        if (stopping || outstanding)
+            return;
+        outstanding = refresh().catch(() => {
+            process.stderr.write(JSON.stringify({ level: "warning", event: "writer_refresh_failed", code: "writer_refresh_failed" }) + "\n");
+        }).finally(() => { outstanding = undefined; });
+    }, REFRESH_INTERVAL_MS) : undefined;
+    let closed = false;
+    let exitCode = 1;
+    let spawnFailed = false;
+    let resolveClosed;
+    const childClosed = new Promise((resolve) => { resolveClosed = resolve; });
+    let cleanup;
+    let resolveExit;
+    let rejectExit;
+    const finished = new Promise((resolve, reject) => { resolveExit = resolve; rejectExit = reject; });
+    const stop = (signal) => {
+        if (cleanup)
+            return cleanup;
+        stopping = true;
+        if (timer !== undefined)
+            deps.clearInterval(timer);
+        cleanup = (async () => {
+            let timeout;
+            const bounded = new Promise((resolve) => { timeout = setTimeout(resolve, LAUNCHER_CLEANUP_BOUND_MS); });
+            try {
+                await outstanding;
+                await Promise.race([childClosed, bounded]);
+                if (!closed) {
+                    await deps.runner.run("podman", ["rm", "-f", "-t", "0", writerContainerName(name)], AbortSignal.timeout(20_000), { inheritFds: [lease.fd] }).catch(() => undefined);
+                }
+                await ensureAbsent();
+                return exitCode;
+            }
+            finally {
+                clearTimeout(timeout);
+                process.off("SIGINT", interrupt);
+                process.off("SIGTERM", terminate);
+                process.off("SIGHUP", terminate);
+                process.stdin.off("end", endOfInput);
+                if (child.stdin) {
+                    process.stdin.unpipe(child.stdin);
+                    child.stdin.destroy();
+                    process.stdin.pause();
+                }
+                // A wedged Podman client still retains its inherited lease, but must not pin this launcher.
+                if (!closed)
+                    child.unref?.();
+            }
+        })();
+        void cleanup.then(resolveExit, rejectExit);
+        // Publish the shared cleanup promise before forwarding a signal can produce close.
+        if (signal && !closed)
+            child.kill(signal);
+        return cleanup;
+    };
+    const interrupt = () => { void stop("SIGINT"); };
+    const terminate = () => { void stop("SIGTERM"); };
+    // End of input is passed on through the pipe, not as a signal: a relayed server shuts down on EOF and a
+    // finite acceptance probe needs EOF to run at all. Cleanup starts and waits, bounded, for the child to close.
+    const endOfInput = () => { void stop(); };
+    process.on("SIGINT", interrupt);
+    process.on("SIGTERM", terminate);
+    process.on("SIGHUP", terminate);
+    process.stdin.once("end", endOfInput);
+    {
+        // Signal/EOF cleanup and child-exit cleanup share exactly one completion.
+        const complete = () => { void stop(); };
+        const onClose = (code, signal) => {
+            closed = true;
+            exitCode = spawnFailed ? 1 : code ?? (signal === "SIGINT" ? 130 : signal === "SIGTERM" ? 143 : 1);
+            resolveClosed();
+            complete();
+        };
+        child.once("error", () => { spawnFailed = true; launchFailure("spawn"); complete(); });
+        child.once("close", onClose);
+        // Attach before piping: EOF can arrive immediately, and must not steal MCP input.
+        if (child.stdin) {
+            // Podman can close its pipe before the host notices; cleanup still owns the fence.
+            child.stdin.once("error", terminate);
+            process.stdin.pipe(child.stdin);
+        }
+        if (process.stdin.readableEnded) {
+            child.stdin?.end();
+            endOfInput();
+        }
+    }
+    return finished;
+}
+if (isEntryPoint(import.meta.url, process.argv[1])) {
+    void launchEntry(process.argv.slice(2), {
+        home: homedir(), releaseRoot: resolve(dirname(fileURLToPath(import.meta.url)), ".."),
+        runner: createProcessRunner(), spawnPodman: (args, inheritFds) => spawn("podman", args, { stdio: ["pipe", "inherit", "inherit", ...inheritFds] }),
+        env: process.env, now: Date.now, setInterval, clearInterval,
+    }).then((code) => { process.exitCode = code; });
+}

package/dist/writer-lease.d.ts

@@ -0,0 +1,28 @@
+import { type StatfsReader } from "./setup-platform.js";
+export declare const LEASE_DIRECTORY: readonly [".local", "state", "pi-session-mcp", "leases"];
+export declare class WriterLeaseError extends Error {
+    readonly code: "writer_busy" | "writer_lease_unavailable";
+    constructor(code: "writer_busy" | "writer_lease_unavailable");
+}
+export interface WriterLease {
+    readonly fd: number;
+    release(): Promise<void>;
+}
+interface LeaseSeams {
+    readonly signal?: AbortSignal;
+    readonly flockCandidates?: readonly string[];
+    readonly isTrustedBinary?: (path: string) => boolean;
+    readonly readStatfs?: StatfsReader;
+}
+export declare function writerLeasePath(home: string, name: string): string;
+export declare function acquireWriterLease(home: string, name: string, options: LeaseSeams & {
+    waitMs: number;
+}): Promise<WriterLease>;
+/**
+ * Adopts a descriptor a parent passed down while it holds the lease. A fresh open must find the
+ * lock busy before the descriptor is touched; if the holder released in between, the descriptor's
+ * own `flock -n` takes the lock instead, which still leaves exactly one exclusive holder. Adopt the
+ * same descriptor once: `release()` closes that descriptor number.
+ */
+export declare function adoptInheritedLease(home: string, name: string, fd: number, options?: LeaseSeams): Promise<WriterLease>;
+export {};

package/dist/writer-lease.js

@@ -0,0 +1,140 @@
+import { close, constants, fstat } from "node:fs";
+import { chmod, lstat, mkdir, open } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { flockBinary, lockWithFlock, OverrideLockError } from "./override-lock.js";
+import { assertSupportedFilesystem } from "./setup-platform.js";
+import { WRITER_NAME_PATTERN } from "./writer-state.js";
+export const LEASE_DIRECTORY = [".local", "state", "pi-session-mcp", "leases"];
+export class WriterLeaseError extends Error {
+    code;
+    constructor(code) {
+        super("Writer lease is not available");
+        this.code = code;
+        this.name = "WriterLeaseError";
+    }
+}
+export function writerLeasePath(home, name) {
+    if (!WRITER_NAME_PATTERN.test(name))
+        throw new WriterLeaseError("writer_lease_unavailable");
+    return join(home, ...LEASE_DIRECTORY, `${name}.lock`);
+}
+function checkFile(file) {
+    if (!file.isFile() || file.uid !== process.getuid() || (file.mode & 0o7777) !== 0o600) {
+        throw new WriterLeaseError("writer_lease_unavailable");
+    }
+}
+async function checkPath(path, descriptor) {
+    checkFile(descriptor);
+    const linked = await lstat(path);
+    checkFile(linked);
+    if (descriptor.dev !== linked.dev || descriptor.ino !== linked.ino)
+        throw new WriterLeaseError("writer_lease_unavailable");
+}
+async function prepare(home, name, options, create) {
+    if (process.platform !== "linux" || options.signal?.aborted)
+        throw new WriterLeaseError("writer_lease_unavailable");
+    const path = writerLeasePath(home, name);
+    const binary = flockBinary(options);
+    if (!binary)
+        throw new WriterLeaseError("writer_lease_unavailable");
+    const directory = join(home, ...LEASE_DIRECTORY);
+    // The umask may narrow the requested modes; a directory this call created gets its exact mode.
+    if (create && await mkdir(directory, { recursive: true, mode: 0o700 }) !== undefined)
+        await chmod(directory, 0o700);
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.uid !== process.getuid() || (info.mode & 0o7777) !== 0o700)
+        throw new WriterLeaseError("writer_lease_unavailable");
+    await assertSupportedFilesystem(directory, "linux", options.readStatfs);
+    return { path, binary };
+}
+/** Creates the file exclusively and sets its exact mode, or opens the existing one; never follows a link. */
+async function openLeaseFile(path) {
+    try {
+        const created = await open(path, constants.O_NOFOLLOW | constants.O_CREAT | constants.O_EXCL | constants.O_RDWR, 0o600);
+        try {
+            await created.chmod(0o600);
+        }
+        catch (error) {
+            await created.close().catch(() => undefined);
+            throw error;
+        }
+        return created;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        return open(path, constants.O_NOFOLLOW | constants.O_RDWR);
+    }
+}
+function lease(fd, closeDescriptor) {
+    let released = false;
+    return {
+        fd,
+        async release() {
+            if (released)
+                return;
+            released = true;
+            // Never unlock explicitly: mutating children can still hold this open file description.
+            await closeDescriptor().catch(() => undefined);
+        },
+    };
+}
+export async function acquireWriterLease(home, name, options) {
+    let handle;
+    try {
+        if (!Number.isFinite(options.waitMs) || options.waitMs < 0)
+            throw new WriterLeaseError("writer_lease_unavailable");
+        const { path, binary } = await prepare(home, name, options, true);
+        handle = await openLeaseFile(path);
+        checkFile(await handle.stat());
+        await lockWithFlock(binary, handle.fd, options.waitMs, options.signal, options.waitMs === 0);
+        await checkPath(path, await handle.stat());
+        const held = handle;
+        return lease(held.fd, () => held.close());
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        throw new WriterLeaseError(error instanceof OverrideLockError && error.code === "override_lock_busy" ? "writer_busy" : "writer_lease_unavailable");
+    }
+}
+/**
+ * Adopts a descriptor a parent passed down while it holds the lease. A fresh open must find the
+ * lock busy before the descriptor is touched; if the holder released in between, the descriptor's
+ * own `flock -n` takes the lock instead, which still leaves exactly one exclusive holder. Adopt the
+ * same descriptor once: `release()` closes that descriptor number.
+ */
+export async function adoptInheritedLease(home, name, fd, options = {}) {
+    let probe;
+    try {
+        if (!Number.isInteger(fd) || fd < 0)
+            throw new WriterLeaseError("writer_lease_unavailable");
+        const { path, binary } = await prepare(home, name, options, false);
+        await checkPath(path, await promisify(fstat)(fd));
+        probe = await open(path, constants.O_NOFOLLOW | constants.O_RDWR);
+        await checkPath(path, await probe.stat());
+        // A fresh open must be excluded BEFORE touching the inherited description; otherwise
+        // flock on an unlocked inherited fd would itself acquire a lock and falsely prove ownership.
+        let busy = false;
+        try {
+            await lockWithFlock(binary, probe.fd, 0, options.signal, true);
+        }
+        catch (error) {
+            if (!(error instanceof OverrideLockError) || error.code !== "override_lock_busy")
+                throw error;
+            busy = true;
+        }
+        if (!busy)
+            throw new WriterLeaseError("writer_lease_unavailable");
+        await lockWithFlock(binary, fd, 0, options.signal, true);
+        await checkPath(path, await promisify(fstat)(fd));
+        return lease(fd, () => promisify(close)(fd));
+    }
+    catch {
+        // Rejection does not take ownership of the caller's descriptor.
+        throw new WriterLeaseError("writer_lease_unavailable");
+    }
+    finally {
+        await probe?.close().catch(() => undefined);
+    }
+}

package/dist/writer-lifecycle.d.ts

@@ -0,0 +1,96 @@
+import type { CommandRunner } from "./client-adapters/types.js";
+import type { ContainerSettings } from "./execution-modes.js";
+export interface WriterContext {
+    home: string;
+    releaseRoot: string;
+    nodePath: string;
+    runner: CommandRunner;
+    checkout: string;
+    alias: string;
+    leaseFd?: number;
+}
+export type WriterOutcome = {
+    code: string;
+    status: "ok" | "planned" | "unchanged" | "failed";
+};
+export declare function containedBuiltinSkills(rawConfig: unknown, overrideDirectory?: string): ReadonlySet<string>;
+export declare function containedProfileRefused(rawConfig: unknown, profileName: string, availableBuiltinSkills: ReadonlySet<string>): boolean;
+/**
+ * `overrideDirectory` is the operator's skill override directory of the host configuration. The boundary has none, so a
+ * `builtin:` skill resolves there only to the shipped skill: one without a shipped skill, or one the operator overrides,
+ * would fail to load or be replaced silently, and is refused instead (#135).
+ */
+export declare function renderContainedConfig(alias: string, clonePath: string, rawConfig: unknown, selected: readonly string[], overrideDirectory?: string): {
+    events?: {
+        delivery: "off" | "spool";
+    } | undefined;
+    workspaces: Record<string, string>;
+    skillCatalog?: Record<string, string> | undefined;
+    executionProfiles: Record<string, {
+        default: boolean;
+        permissionProfile: "coding" | "read-only";
+        provider: string;
+        model: string;
+        thinkingLevel: "high" | "low" | "max" | "medium" | "minimal" | "off" | "xhigh";
+        mcpServers?: Readonly<Record<string, import("./mcp-config.js").McpServerConfig>> | undefined;
+        extensions?: string[] | undefined;
+        grantedExtensionTools?: string[] | undefined;
+        skills?: string[] | undefined;
+    }>;
+};
+/** The short branch name provisioning would record for `requested` (or its default base), normalized like the writer state. */
+export declare function baseBranchName(ctx: WriterContext, requested?: string): Promise<string>;
+type ProvisionInput = {
+    settings: ContainerSettings;
+    rawConfig: unknown;
+    overrideDirectory?: string;
+};
+/**
+ * Reconcile's check of a kept writer (#134): `undefined` while the writer matches the settings and configuration it
+ * would be provisioned from now; otherwise the finding, usually `writer_settings_changed`. A writer without
+ * provisioned state is only rendered, so the dry run shows a profile that provisioning would refuse. The image is
+ * resolved locally and never pulled: `podman_unavailable` when Podman cannot be asked, `image_unavailable` when it
+ * answers but cannot resolve the image.
+ */
+export declare function writerSettingsDrift(ctx: WriterContext, input: ProvisionInput & {
+    index: number;
+}): Promise<WriterOutcome | undefined>;
+export declare function provisionWriter(ctx: WriterContext, input: {
+    index: number;
+    settings: ContainerSettings;
+    baseRef?: string;
+    rawConfig: unknown;
+    overrideDirectory?: string;
+}): Promise<WriterOutcome>;
+export declare function inspectWork(ctx: WriterContext, name: string): Promise<{
+    baseline: boolean;
+    digest: string;
+    branches: readonly {
+        name: string;
+        commit: string;
+    }[];
+    dirty: boolean;
+}>;
+export type CollectOutcome = WriterOutcome & {
+    refs: readonly string[];
+    refused: number;
+    findings: readonly {
+        code: "ref_name_refused";
+    }[];
+};
+export declare function collectWriter(ctx: WriterContext, name: string): Promise<CollectOutcome>;
+export declare function recreateWriter(ctx: WriterContext, name: string, opts: {
+    discard: boolean;
+    baseRef?: string;
+}): Promise<WriterOutcome>;
+export declare function resetWriter(ctx: WriterContext, name: string, opts: {
+    discard: boolean;
+    baseRef?: string;
+}): Promise<WriterOutcome>;
+export declare function finishWriter(ctx: WriterContext, name: string, opts?: {
+    baseRef?: string;
+}): Promise<WriterOutcome>;
+export declare function removeWriter(ctx: WriterContext, name: string, opts: {
+    discard: boolean;
+}): Promise<WriterOutcome>;
+export {};