@parcha/agentrun-pi 0.1.0-beta.2 → 0.1.0-beta.21

package/dist/signin/signin.js

@@ -0,0 +1,126 @@
+// Sign in with ChatGPT through pi-ai's own flow (`openaiChatGPTOAuth.login`), unchanged. We pass the two options it
+// takes: `agentName`, this app's name rather than pi's, and `getDeviceId`, the host id kept in auth.json. The credential
+// it returns goes straight into the file store through pi-ai's `Models.login`; nothing here sees or prints a token.
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { createModels } from "@earendil-works/pi-ai/models";
+import { openaiProvider } from "@earendil-works/pi-ai/providers/openai";
+import { agentrunHome, fileCredentialStore } from "./store.js";
+export const AGENT_NAME = "AgentRun";
+/** pi-ai's provider id for OpenAI, whose OAuth method is Sign in with ChatGPT. */
+export const CHATGPT_PROVIDER = "openai";
+export class SignInError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "SignInError";
+    }
+}
+/** A pi-ai collection with only OpenAI, whose credentials live in `store`. */
+export function chatgptModels(store) {
+    const models = createModels({ credentials: store });
+    models.setProvider(openaiProvider());
+    return models;
+}
+/**
+ * Sign in once per install; the token refreshes on its own afterwards. The sign-in page must name this app: pi-ai
+ * before 1.1 ignores `agentName` and names pi, so a page that names anything else is never shown, and the sign-in fails
+ * with `SignInError` ("APP_NAME_IGNORED") before the browser opens.
+ */
+export async function signIn(options = {}) {
+    const home = agentrunHome(options.home, options.env);
+    const agentName = options.agentName ?? AGENT_NAME;
+    const store = fileCredentialStore(home);
+    const hostId = await store.hostId();
+    const inner = options.interaction ?? consoleInteraction();
+    const stop = new AbortController();
+    let named;
+    const interaction = {
+        signal: inner.signal ? AbortSignal.any([inner.signal, stop.signal]) : stop.signal,
+        notify(event) {
+            if (event.type === "auth_url" && (named = new URL(event.url).searchParams.get("agent_name_hint")) !== agentName)
+                return stop.abort();
+            inner.notify(event);
+        },
+        // pi-ai's login ends only when the browser's callback comes or this prompt rejects, and its callback server holds
+        // port 1455 until then: a cancel rejects the prompt even when the interaction's own prompt does not watch it.
+        prompt: (prompt) => {
+            if (stop.signal.aborted)
+                return Promise.reject(stop.signal.reason);
+            const cancel = prompt.signal;
+            if (!cancel)
+                return inner.prompt(prompt);
+            if (cancel.aborted)
+                return Promise.reject(cancel.reason);
+            return new Promise((resolve, reject) => {
+                const onAbort = () => reject(cancel.reason);
+                cancel.addEventListener("abort", onAbort, { once: true });
+                inner.prompt(prompt).then(resolve, reject).finally(() => cancel.removeEventListener("abort", onAbort));
+            });
+        },
+    };
+    // A variable, not a literal: pi-ai before 1.1 has no `agentName` in its `LoginOptions` type, and the page check above
+    // refuses those versions at run time.
+    const loginOptions = { agentName, getDeviceId: () => hostId };
+    let credential;
+    try {
+        credential = await chatgptModels(store).login(CHATGPT_PROVIDER, "oauth", interaction, loginOptions);
+    }
+    catch (error) {
+        if (stop.signal.aborted) {
+            throw new SignInError("APP_NAME_IGNORED", `The installed pi-ai names ${named ? `"${named}"` : "no app"} on the sign-in page instead of "${agentName}": it ignores the app name. Sign in with ChatGPT needs a pi-ai that passes it on (1.1.0 or later).`, { cause: error });
+        }
+        // pi-ai's callback port is fixed at 1455, and its message for a taken port names the likely holder.
+        if (error instanceof Error && /\bPort 1455 is in use\b/.test(error.message)) {
+            throw new SignInError("PORT_IN_USE", `${error.message}\nFinish or cancel the other login, then run again.`, { cause: error });
+        }
+        throw error;
+    }
+    return { home, provider: CHATGPT_PROVIDER, hostId, expires: credential.type === "oauth" ? credential.expires : 0 };
+}
+/** The terminal: prints the sign-in page's address and opens it, then waits for the browser's callback or, on a
+ *  terminal, a pasted redirect address. The page address carries no token. */
+export function consoleInteraction(io = {}) {
+    const input = io.input ?? process.stdin;
+    const output = io.output ?? process.stderr;
+    const open = io.open ?? (process.env.AGENTRUN_NO_BROWSER ? undefined : openBrowser);
+    return {
+        notify(event) {
+            if (event.type === "auth_url") {
+                output.write(`Continue with ChatGPT: sign in at\n  ${event.url}\n${event.instructions ? `${event.instructions}\n` : ""}`);
+                open?.(event.url);
+            }
+            else if (event.type === "progress" || event.type === "info") {
+                output.write(`${event.message}\n`);
+            }
+        },
+        prompt(prompt) {
+            return new Promise((done, fail) => {
+                const signal = prompt.signal;
+                if (signal?.aborted)
+                    return fail(signal.reason);
+                // Off a terminal only the browser's callback can finish the sign-in; the prompt waits to be cancelled.
+                const lines = input.isTTY ? createInterface({ input, output }) : undefined;
+                const onAbort = () => { lines?.close(); fail(signal?.reason); };
+                signal?.addEventListener("abort", onAbort, { once: true });
+                lines?.question(`${prompt.message} `, (answer) => {
+                    signal?.removeEventListener("abort", onAbort);
+                    lines.close();
+                    done(answer);
+                });
+            });
+        },
+    };
+}
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin" ? ["open", [url]]
+        : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch { /* no opener: the address is printed */ }
+}

package/dist/signin/spec.d.ts

@@ -0,0 +1,116 @@
+/** A run mode an item is needed for: `live` (paid calls) or `kill` (the kill on a real box). Without `for`, every run. */
+export type RunMode = "live" | "kill";
+export type Platform = "linux" | "darwin" | "win32";
+export type Key = {
+    env: string;
+    why: string;
+    where: string;
+    required: boolean;
+    for?: RunMode;
+};
+/** `min` is an x.y.z version, compared with the first x.y.z that `<cmd> --version` prints. */
+export type Program = {
+    cmd: string;
+    why: string;
+    required: boolean;
+    platforms?: Platform[];
+    min?: string;
+    for?: RunMode;
+};
+/** An npm package the demo loads only when used, installed with `--no-save` so it is never a dependency. */
+export type Package = {
+    name: string;
+    version: string;
+    why: string;
+    required: boolean;
+    for?: RunMode;
+};
+/** One of its members; an array member means all of its items (a key pair, or a key with its package). */
+export type Choice = {
+    oneOf: Array<Key | Program | Package | Array<Key | Program | Package>>;
+    why: string;
+    for?: RunMode;
+};
+export type ModelNeed = "text" | "tools" | "images";
+export type EyesNeed = "images" | "video";
+export type DemoSpec = {
+    name: string;
+    models: {
+        lead: {
+            needs: ModelNeed[];
+            default?: string;
+        };
+        /** A second model the run calls itself. */
+        eyes?: {
+            needs: EyesNeed[];
+            default?: string;
+        };
+        judge?: {
+            jev: true;
+        };
+    };
+    keys: Array<Key | Choice>;
+    programs: Array<Program | Choice>;
+    packages?: Array<Package | Choice>;
+    expectedCalls: number;
+    /** USD for one `--live` run. */
+    expectedCost: number;
+};
+/** Jev in a stranger's run: its own key, or Jev through OpenRouter. Nothing is substituted silently. */
+export declare const JEV_KEYS: Choice;
+export type CheckOptions = {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    /** The demo's directory, where its packages resolve from. Default: the current directory. */
+    dir?: string;
+    live?: boolean;
+    kill?: boolean;
+    /** An explicit eyes model (`--eyes-model`); its key is checked when the model is resolved. */
+    eyes?: {
+        provider: string;
+        model: string;
+    };
+};
+/** One requirement of this run and whether this machine meets it. `fix` says what to do, never a value. */
+export type ReportItem = {
+    kind: "key" | "program" | "package" | "choice" | "model";
+    name: string;
+    why: string;
+    required: boolean;
+    met: boolean;
+    fix?: string;
+};
+export type KeyReport = {
+    ok: boolean;
+    /** 2 when a required item is missing: nothing may start. */
+    exitCode: 0 | 2;
+    items: ReportItem[];
+    missing: ReportItem[];
+    expectedCalls: number;
+    expectedCost: number;
+    /** The report as printed: every requirement, what is missing and how to fix it. */
+    text: string;
+};
+/**
+ * What this demo needs for this run, and what is missing. Items whose `for` is not this run's mode are left out, choice
+ * members included; `kill` implies `live`. A choice is met by any member, an array member only when all of its items
+ * are. A relative `dir` is taken from the current directory. A required program
+ * outside its platforms is missing, before anything starts, and so is one below its `min` or whose version cannot be
+ * read. It sends no request and prompts for nothing, so a run that checks first sends nothing while a required item is
+ * missing (`exitCode` 2).
+ */
+export declare function checkKeys(spec: DemoSpec, options?: CheckOptions): KeyReport;
+export type SetupPromptReport = {
+    ok: boolean;
+    /** Spec names the prompt never mentions: key env names, program commands and package names, choice members included. */
+    missing: string[];
+    /** Credential env names the prompt mentions that the spec does not list. */
+    extra: string[];
+};
+/**
+ * Whether a demo's SETUP-PROMPT.md matches its spec. Every key env name, program command and package name in the spec,
+ * choice members included, appears in the prompt. "Nothing more" covers credential env names only: an UPPER_SNAKE name
+ * that reads as a credential and is not in the spec fails. A prompt's own command words (sudo, an install step) are
+ * never read as programs.
+ */
+export declare function checkSetupPrompt(spec: DemoSpec, text: string): SetupPromptReport;

package/dist/signin/spec.js

@@ -0,0 +1,181 @@
+// What a demo needs, and the key check that runs before anything else. Neither check sends a request or prompts. They
+// read only the environment they are given, the PATH in it and the demo's own node_modules, and the key check runs one
+// process: `<cmd> --version`, for a program with a minimum version. A key's value is never read past "is it set", and
+// never printed.
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { delimiter, join, resolve } from "node:path";
+/** Jev in a stranger's run: its own key, or Jev through OpenRouter. Nothing is substituted silently. */
+export const JEV_KEYS = {
+    oneOf: [
+        { env: "TYPESAFE_API_KEY", why: "Jev's typed judgments", where: "https://console.typesafe.ai/keys", required: true },
+        { env: "OPENROUTER_API_KEY", why: "Jev through OpenRouter", where: "https://openrouter.ai/keys", required: true },
+    ],
+    why: "the judge is Jev",
+    for: "live",
+};
+const isChoice = (item) => "oneOf" in item;
+const isKey = (item) => "env" in item;
+const isProgram = (item) => "cmd" in item;
+const nameOf = (item) => isKey(item) ? item.env : isProgram(item) ? item.cmd : `${item.name}@${item.version}`;
+/** Every requirement of `spec`, the implied ones included: Jev's keys when the judge is Jev. */
+function requirements(spec) {
+    return [...spec.keys, ...(spec.models.judge?.jev ? [JEV_KEYS] : []), ...spec.programs, ...(spec.packages ?? [])];
+}
+/** The file `cmd` runs from `env`'s PATH, or undefined when it is not there. */
+function onPath(cmd, ctx) {
+    const exts = ctx.platform === "win32" ? ["", ...(ctx.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";")] : [""];
+    for (const dir of (ctx.env.PATH ?? ctx.env.Path ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const file = join(dir, cmd + ext);
+            try {
+                if (!statSync(file).isFile())
+                    continue;
+                accessSync(file, constants.X_OK);
+                return file;
+            }
+            catch { /* not this one */ }
+        }
+    }
+    return undefined;
+}
+const XYZ = /(\d+)\.(\d+)\.(\d+)/;
+const versionParts = (version) => XYZ.exec(version)?.slice(1, 4).map(Number);
+/** The first x.y.z that `file --version` prints, stdout before stderr; undefined when it prints none, fails or hangs. */
+function programVersion(file, ctx) {
+    const shell = ctx.platform === "win32" && /\.(cmd|bat)$/i.test(file);
+    const run = spawnSync(file, ["--version"], { env: ctx.env, encoding: "utf8", timeout: 10_000, stdio: ["ignore", "pipe", "pipe"], shell });
+    return run.status === 0 ? XYZ.exec(`${run.stdout}\n${run.stderr}`)?.[0] : undefined;
+}
+/** Whether x.y.z `found` is at least `min`. */
+function atLeast(found, min) {
+    const [a, b] = [versionParts(found), versionParts(min)];
+    for (let i = 0; i < 3; i += 1)
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    return true;
+}
+/** The version of `name` that Node would load from `dir`, or undefined when it resolves nowhere. */
+function installedVersion(name, dir) {
+    for (const base of createRequire(join(dir, "noop.js")).resolve.paths(name) ?? []) {
+        const manifest = join(base, name, "package.json");
+        if (!existsSync(manifest))
+            continue;
+        try {
+            return String(JSON.parse(readFileSync(manifest, "utf8")).version);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/** Whether `item` is met here, and the fix when it is not. */
+function checkMember(item, ctx) {
+    if (isKey(item))
+        return ctx.env[item.env] ? { met: true } : { met: false, fix: `set ${item.env} (create it: ${item.where})` };
+    if (isProgram(item)) {
+        if (item.platforms && !item.platforms.includes(ctx.platform)) {
+            return { met: false, fix: `${item.cmd} runs on ${item.platforms.join(" or ")} only; this machine is ${ctx.platform}` };
+        }
+        const file = onPath(item.cmd, ctx);
+        if (!file)
+            return { met: false, fix: `install ${item.cmd}${item.min ? ` ${item.min} or later` : ""}; it is not on PATH` };
+        if (!item.min)
+            return { met: true };
+        if (!versionParts(item.min))
+            return { met: false, fix: `the spec's minimum for ${item.cmd} (${item.min}) is not an x.y.z version` };
+        const found = programVersion(file, ctx);
+        if (!found)
+            return { met: false, fix: `${item.cmd} --version printed no x.y.z version, so ${item.min} or later cannot be confirmed` };
+        return atLeast(found, item.min) ? { met: true } : { met: false, fix: `${item.cmd} is ${found}; this run needs ${item.min} or later` };
+    }
+    const found = installedVersion(item.name, ctx.dir);
+    if (found === item.version)
+        return { met: true };
+    const install = `npm install --no-save ${item.name}@${item.version}`;
+    return { met: false, fix: found === undefined ? install : `${install} (found ${found})` };
+}
+const applies = (item, options) => !item.for || (item.for === "live" ? options.live || options.kill : options.kill) === true;
+/**
+ * What this demo needs for this run, and what is missing. Items whose `for` is not this run's mode are left out, choice
+ * members included; `kill` implies `live`. A choice is met by any member, an array member only when all of its items
+ * are. A relative `dir` is taken from the current directory. A required program
+ * outside its platforms is missing, before anything starts, and so is one below its `min` or whose version cannot be
+ * read. It sends no request and prompts for nothing, so a run that checks first sends nothing while a required item is
+ * missing (`exitCode` 2).
+ */
+export function checkKeys(spec, options = {}) {
+    const ctx = { env: options.env ?? process.env, platform: options.platform ?? process.platform, dir: resolve(options.dir ?? ".") };
+    const items = [];
+    for (const item of requirements(spec)) {
+        if (!applies(item, options))
+            continue;
+        if (!isChoice(item)) {
+            const kind = isKey(item) ? "key" : isProgram(item) ? "program" : "package";
+            items.push({ kind, name: nameOf(item), why: item.why, required: item.required, ...checkMember(item, ctx) });
+            continue;
+        }
+        // A member's own `for` applies too: an item this mode does not need drops out of its member, and a member left with
+        // nothing drops out of the choice, which this mode then does not need at all.
+        const members = item.oneOf.map((member) => (Array.isArray(member) ? member : [member]).filter((one) => applies(one, options))).filter((all) => all.length);
+        if (!members.length)
+            continue;
+        const options_ = members.map((all) => {
+            const checked = all.map((one) => ({ one, ...checkMember(one, ctx) }));
+            return { name: all.map(nameOf).join(" + "), met: checked.every((one) => one.met), fixes: checked.filter((one) => !one.met).map((one) => one.fix) };
+        });
+        const met = options_.some((option) => option.met);
+        items.push({
+            kind: "choice", name: options_.map((option) => option.name).join(" or "), why: item.why, required: true, met,
+            ...(met ? {} : { fix: `one of: ${options_.map((option) => option.fixes.join(", ")).join("; or ")}` }),
+        });
+    }
+    const eyes = spec.models.eyes;
+    if (eyes && (options.live || options.kill) && eyes.needs.includes("video") && !options.eyes) {
+        items.push({
+            kind: "model", name: "eyes", why: "the run's eyes read video", required: true, met: false,
+            fix: "the ChatGPT plan takes no video input, and the lead model's catalog lists none; name a model that reads video natively with --eyes-model and set its provider's key, or list images and let frames be extracted locally",
+        });
+    }
+    const missing = items.filter((item) => item.required && !item.met);
+    const mode = options.kill ? "--live --kill" : options.live ? "--live" : "on fakes";
+    const lines = [`${spec.name} (${mode}) needs:`];
+    for (const item of items) {
+        const state = item.met ? "ok      " : item.required ? "MISSING " : "optional";
+        lines.push(`  ${state} ${item.kind} ${item.name}: ${item.why}`);
+        if (!item.met)
+            lines.push(`           ${item.fix}`);
+    }
+    if (options.live || options.kill) {
+        lines.push("  model: Sign in with ChatGPT (your plan pays), or --provider and --model with that provider's key");
+        lines.push(`Expected: about ${spec.expectedCalls} model calls, about $${spec.expectedCost.toFixed(2)} at list prices.`);
+    }
+    lines.push(missing.length
+        ? `${missing.length} required ${missing.length === 1 ? "item is" : "items are"} missing, so nothing started. SETUP-PROMPT.md beside this demo walks through each one.`
+        : "Everything this run needs is here.");
+    return { ok: missing.length === 0, exitCode: missing.length ? 2 : 0, items, missing, expectedCalls: spec.expectedCalls, expectedCost: spec.expectedCost, text: lines.join("\n") };
+}
+/** An UPPER_SNAKE name that reads as a credential: `*_API_KEY`, `*_KEY`, `*_TOKEN*`, `*_SECRET*`, `*_PROJECT_ID`. */
+const CREDENTIAL = /_(API_)?KEY$|_TOKEN|_SECRET|_PROJECT_ID$/;
+const ENV_NAME = /(?<![A-Za-z0-9_])[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+(?![A-Za-z0-9_])/g;
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** `name` as a whole word: not part of a longer name, a path, or a hyphenated command. */
+const mentions = (text, name) => new RegExp(`(?<![A-Za-z0-9_@/.-])${escape(name)}(?![A-Za-z0-9_/-])`).test(text);
+/**
+ * Whether a demo's SETUP-PROMPT.md matches its spec. Every key env name, program command and package name in the spec,
+ * choice members included, appears in the prompt. "Nothing more" covers credential env names only: an UPPER_SNAKE name
+ * that reads as a credential and is not in the spec fails. A prompt's own command words (sudo, an install step) are
+ * never read as programs.
+ */
+export function checkSetupPrompt(spec, text) {
+    const members = requirements(spec).flatMap((item) => isChoice(item) ? item.oneOf.flat() : [item]);
+    const names = members.map((item) => isKey(item) ? item.env : isProgram(item) ? item.cmd : item.name);
+    const envs = new Set(members.filter(isKey).map((item) => item.env));
+    const missing = [...new Set(names)].filter((name) => !mentions(text, name));
+    const extra = [...new Set(text.match(ENV_NAME) ?? [])].filter((name) => CREDENTIAL.test(name) && !envs.has(name));
+    return { ok: missing.length === 0 && extra.length === 0, missing, extra };
+}

package/dist/signin/store.d.ts

@@ -0,0 +1,40 @@
+import type { AuthOperationOptions, Credential, CredentialInfo, CredentialStore } from "@earendil-works/pi-ai";
+/** Where the sign-in lives: `home`, else $AGENTRUN_HOME, else ~/.config/agentrun. */
+export declare function agentrunHome(home?: string, env?: NodeJS.ProcessEnv): string;
+export declare class AuthStoreError extends Error {
+    readonly code: "HOME_MODE" | "LOCK_TIMEOUT" | "CORRUPT";
+    constructor(code: "HOME_MODE" | "LOCK_TIMEOUT" | "CORRUPT", message: string, options?: {
+        cause?: unknown;
+    });
+}
+export type FileCredentialStoreOptions = {
+    /** How long a writer waits for another process's lock before failing. Default 60 s; pi-ai bounds a refresh at 15 s. */
+    lockTimeoutMs?: number;
+};
+export declare class FileCredentialStore implements CredentialStore {
+    readonly home: string;
+    readonly file: string;
+    private readonly lockFile;
+    private readonly lockTimeoutMs;
+    constructor(home: string, options?: FileCredentialStoreOptions);
+    read(providerId: string, options?: AuthOperationOptions): Promise<Credential | undefined>;
+    list(options?: AuthOperationOptions): Promise<readonly CredentialInfo[]>;
+    modify(providerId: string, fn: (current: Credential | undefined) => Promise<Credential | undefined>, options?: AuthOperationOptions): Promise<Credential | undefined>;
+    delete(providerId: string, options?: AuthOperationOptions): Promise<void>;
+    /** This install's host id, a UUID made once and kept in auth.json: the `getDeviceId` of every sign-in from here. */
+    hostId(options?: AuthOperationOptions): Promise<string>;
+    /** Run `fn` on the file as it is under the lock. `signal` cancels only the wait: once `fn` starts, a refresh may have
+     *  rotated the token at the server, so it and its write run to the end. */
+    private exclusive;
+    private load;
+    /** The whole file, written to a new file in the same directory, flushed, then renamed over auth.json. */
+    private save;
+    /** The directory, made 0700 when missing. An existing one that others can reach is refused, not changed. */
+    private ensureHome;
+    /** The cross-process lock: an exclusive transaction on the lock database, taken without blocking the event loop (a
+     *  busy database answers at once and the wait is a timer). Closing the connection ends the transaction and frees it.
+     *  The lock file is created with O_EXCL and never opened or closed by hand afterwards: closing any descriptor of a file
+     *  drops every lock this process holds on it. */
+    private lock;
+}
+export declare function fileCredentialStore(home: string, options?: FileCredentialStoreOptions): FileCredentialStore;

package/dist/signin/store.js

@@ -0,0 +1,206 @@
+// The sign-in's token store: $AGENTRUN_HOME/auth.json, as pi-ai's `CredentialStore`.
+//
+// The directory is 0700 and the file 0600. Every write is the whole file, written beside it and renamed into place, so a
+// reader without the lock always sees one complete version. Writes are serialized inside a process by one chain per file,
+// and across processes by an operating-system lock: an exclusive SQLite transaction on auth.json.lock, an empty
+// database. The system drops that lock when its holder exits or is killed, so there is no abandoned lock to detect or
+// break, and a lock another writer holds is never moved or removed. `modify` re-reads the file under the lock, so
+// pi-ai's refresh, which runs inside `modify` and re-checks expiry there, refreshes once: a process that waited sees the
+// rotated token and leaves it. A token is never written anywhere else, logged or printed.
+import { randomUUID } from "node:crypto";
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+/** Where the sign-in lives: `home`, else $AGENTRUN_HOME, else ~/.config/agentrun. */
+export function agentrunHome(home, env = process.env) {
+    return resolve(home ?? env.AGENTRUN_HOME ?? join(homedir(), ".config", "agentrun"));
+}
+export class AuthStoreError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "AuthStoreError";
+    }
+}
+/** One chain per auth file in this process: every instance on the same file queues on it, so the lock file only ever
+ *  arbitrates between processes. */
+const chains = new Map();
+const sleep = (ms, signal) => new Promise((done, fail) => {
+    const timer = setTimeout(() => { signal?.removeEventListener("abort", onAbort); done(); }, ms);
+    const onAbort = () => { clearTimeout(timer); fail(signal?.reason); };
+    signal?.addEventListener("abort", onAbort, { once: true });
+});
+/** node:sqlite, loaded on the first write: Node 22 marks it experimental and warns once when it loads. */
+let sqlite;
+const SQLITE_BUSY = 5;
+/** Every lock connection this process holds, until its writer releases it. A connection nothing references is closed
+ *  by the garbage collector, and closing it frees the lock: a writer whose own code no longer references its wait would
+ *  otherwise lose the lock while still inside. */
+const held = new Set();
+export class FileCredentialStore {
+    home;
+    file;
+    lockFile;
+    lockTimeoutMs;
+    constructor(home, options = {}) {
+        this.home = home;
+        this.file = join(home, "auth.json");
+        this.lockFile = `${this.file}.lock`;
+        this.lockTimeoutMs = options.lockTimeoutMs ?? 60_000;
+    }
+    async read(providerId, options) {
+        options?.signal?.throwIfAborted();
+        return this.load().credentials[providerId];
+    }
+    async list(options) {
+        options?.signal?.throwIfAborted();
+        return Object.entries(this.load().credentials).map(([providerId, credential]) => ({ providerId, type: credential.type }));
+    }
+    modify(providerId, fn, options) {
+        return this.exclusive(async (file) => {
+            const current = file.credentials[providerId];
+            const next = await fn(current);
+            if (next === undefined)
+                return current;
+            file.credentials[providerId] = next;
+            this.save(file);
+            return next;
+        }, options?.signal);
+    }
+    delete(providerId, options) {
+        return this.exclusive(async (file) => {
+            if (!(providerId in file.credentials))
+                return;
+            delete file.credentials[providerId];
+            this.save(file);
+        }, options?.signal);
+    }
+    /** This install's host id, a UUID made once and kept in auth.json: the `getDeviceId` of every sign-in from here. */
+    hostId(options) {
+        return this.exclusive(async (file) => {
+            if (file.hostId)
+                return file.hostId;
+            file.hostId = randomUUID();
+            this.save(file);
+            return file.hostId;
+        }, options?.signal);
+    }
+    /** Run `fn` on the file as it is under the lock. `signal` cancels only the wait: once `fn` starts, a refresh may have
+     *  rotated the token at the server, so it and its write run to the end. */
+    exclusive(fn, signal) {
+        const previous = chains.get(this.file) ?? Promise.resolve();
+        const run = previous.catch(() => { }).then(async () => {
+            signal?.throwIfAborted();
+            const lock = await this.lock(signal);
+            try {
+                return await fn(this.load());
+            }
+            finally {
+                held.delete(lock);
+                lock.close();
+            }
+        });
+        const tail = run.catch(() => { });
+        chains.set(this.file, tail);
+        void tail.then(() => { if (chains.get(this.file) === tail)
+            chains.delete(this.file); });
+        return run;
+    }
+    load() {
+        let text;
+        try {
+            text = readFileSync(this.file, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { version: 1, credentials: {} };
+            throw error;
+        }
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed?.version !== 1 || typeof parsed.credentials !== "object" || parsed.credentials === null)
+                throw new Error("not an auth file");
+            return parsed;
+        }
+        catch (error) {
+            throw new AuthStoreError("CORRUPT", `${this.file} is not a sign-in file this version reads; move it aside and sign in again`, { cause: error });
+        }
+    }
+    /** The whole file, written to a new file in the same directory, flushed, then renamed over auth.json. */
+    save(file) {
+        this.ensureHome();
+        const temp = join(this.home, `.auth.json.${process.pid}.${randomUUID()}.tmp`);
+        const fd = openSync(temp, "wx", 0o600);
+        try {
+            try {
+                writeSync(fd, `${JSON.stringify(file, null, 2)}\n`);
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            renameSync(temp, this.file);
+        }
+        catch (error) {
+            try {
+                unlinkSync(temp);
+            }
+            catch { /* already renamed or never written */ }
+            throw error;
+        }
+    }
+    /** The directory, made 0700 when missing. An existing one that others can reach is refused, not changed. */
+    ensureHome() {
+        mkdirSync(this.home, { recursive: true, mode: 0o700 });
+        if (process.platform === "win32")
+            return;
+        const stat = statSync(this.home);
+        if ((stat.mode & 0o077) !== 0 || (process.getuid && stat.uid !== process.getuid())) {
+            throw new AuthStoreError("HOME_MODE", `${this.home} must be a directory only you can read (mode 0700, owned by you); it is ${(stat.mode & 0o777).toString(8)}. Run chmod 700 on it, or set AGENTRUN_HOME to a new directory.`);
+        }
+    }
+    /** The cross-process lock: an exclusive transaction on the lock database, taken without blocking the event loop (a
+     *  busy database answers at once and the wait is a timer). Closing the connection ends the transaction and frees it.
+     *  The lock file is created with O_EXCL and never opened or closed by hand afterwards: closing any descriptor of a file
+     *  drops every lock this process holds on it. */
+    async lock(signal) {
+        this.ensureHome();
+        try {
+            closeSync(openSync(this.lockFile, "wx", 0o600));
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        sqlite ??= createRequire(import.meta.url)("node:sqlite");
+        const db = new sqlite.DatabaseSync(this.lockFile);
+        const deadline = Date.now() + this.lockTimeoutMs;
+        try {
+            for (let delay = 5;; delay = Math.min(delay * 2, 100)) {
+                signal?.throwIfAborted();
+                try {
+                    db.exec("BEGIN EXCLUSIVE");
+                    held.add(db);
+                    return db;
+                }
+                catch (error) {
+                    if (error.errcode !== SQLITE_BUSY)
+                        throw error;
+                }
+                if (Date.now() > deadline) {
+                    throw new AuthStoreError("LOCK_TIMEOUT", `${this.lockFile} is held by another process; it was not released within ${Math.round(this.lockTimeoutMs / 1000)} s`);
+                }
+                await sleep(delay + Math.random() * delay, signal);
+            }
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+    }
+}
+export function fileCredentialStore(home, options) {
+    return new FileCredentialStore(home, options);
+}