@alpacakit/agents 0.1.0-beta.19

package/dist/config/store.js

@@ -0,0 +1,420 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { AUTH_MATERIAL_KIND } from "../auth/material.js";
+import { fileFleetStore } from "../fleet/store.js";
+import { AGENT_CONFIG_VALIDATION_RESULT, validateAgentConfig, } from "./agent-config-validation.js";
+import { AGENTS_CONFIG_ERROR_CODE, AgentsConfigError } from "./errors.js";
+import { profileId } from "./ids.js";
+import { AGENTS_CONFIG_FILE_VERSION, agentConfigSettingsFileSchema, profilesFileSchema, } from "./schema.js";
+import { FIELD_PATH, formatFieldPath, isErrnoCode, NODE_ERRNO_CODE, } from "./support.js";
+import { AGENT_CONFIG_KIND, DEFAULT_AGENT_CONFIG_ID } from "./values.js";
+const TEXT_ENCODING = "utf8";
+const PRIVATE_DIRECTORY_MODE = 0o700;
+const PRIVATE_FILE_MODE = 0o600;
+const TEMP_FILE_SUFFIX = "tmp";
+const TEMP_FILE_PATH_SEPARATOR = ".";
+const JSON_INDENT_SPACES = 2;
+const TRAILING_NEWLINE = "\n";
+const FILE_PARSE_ERROR_REASON = {
+    invalidJson: "Invalid JSON.",
+    invalidFile: "Invalid file.",
+};
+const MUTATION_FIELD = {
+    id: "id",
+    agentConfigs: "agentConfigs",
+    profileOrder: "profileIds",
+    agentConfigOrder: "agentConfigIds",
+    agentConfigKind: "kind",
+    agentConfigPayload: "payload",
+};
+const MUTATION_ERROR_REASON = {
+    duplicateProfileId: (id) => `Duplicate profile id "${id}".`,
+    duplicateAgentConfigId: (id) => `Duplicate agent config id "${id}".`,
+    duplicateReorderId: (id) => `Duplicate reorder id "${id}".`,
+    missingProfileId: (id) => `Missing profile id "${id}".`,
+    missingAgentConfigId: (id) => `Missing agent config id "${id}".`,
+    incompleteProfileOrder: "Profile order must include each profile exactly once.",
+    incompleteAgentConfigOrder: "Agent config order must include each agent config exactly once.",
+    unknownAgentConfigKind: (kind) => `Unknown agent config kind "${kind}".`,
+    invalidAgentConfigPayload: (issues) => `Invalid agent config payload: ${issues.join(ERROR_ISSUE_SEPARATOR)}`,
+};
+const ERROR_ISSUE_SEPARATOR = "; ";
+export const DEFAULT_AGENTS_CONFIG_AGENT_SETTINGS = {
+    ambientBuiltinAuth: { enabled: true },
+    agentConfigs: [
+        {
+            id: DEFAULT_AGENT_CONFIG_ID.codex,
+            kind: AGENT_CONFIG_KIND.codex,
+            enabled: true,
+            payload: { model: null, effort: null },
+        },
+        {
+            id: DEFAULT_AGENT_CONFIG_ID.claude,
+            kind: AGENT_CONFIG_KIND.claude,
+            enabled: true,
+            payload: { model: null, effort: null },
+        },
+    ],
+};
+class FileProfileManager {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async list() {
+        return await this.store.list();
+    }
+    async addHomeDir(input) {
+        const profile = {
+            id: profileId(input.id),
+            agentId: input.agentId,
+            material: {
+                kind: AUTH_MATERIAL_KIND.homeDir,
+                path: input.path,
+            },
+        };
+        return await this.addProfile(profile);
+    }
+    async addApiKey(input) {
+        const profile = {
+            id: profileId(input.id),
+            agentId: input.agentId,
+            material: {
+                kind: AUTH_MATERIAL_KIND.apiKey,
+                secret: input.secret,
+            },
+        };
+        return await this.addProfile(profile);
+    }
+    async remove(id) {
+        const profiles = await this.store.list();
+        const profile = profiles.find((entry) => entry.id === id);
+        if (profile === undefined) {
+            return null;
+        }
+        await this.store.save(profiles.filter((entry) => entry.id !== id));
+        return profile;
+    }
+    async reorder(ids) {
+        const profiles = await this.store.list();
+        const reordered = reorderRecords({
+            ids,
+            records: profiles,
+            idOf: (profile) => profile.id,
+            field: MUTATION_FIELD.profileOrder,
+            duplicateReason: MUTATION_ERROR_REASON.duplicateReorderId,
+            missingReason: MUTATION_ERROR_REASON.missingProfileId,
+            incompleteReason: MUTATION_ERROR_REASON.incompleteProfileOrder,
+        });
+        await this.store.save(reordered);
+        return reordered;
+    }
+    async clear() {
+        await this.store.save([]);
+    }
+    async addProfile(profile) {
+        const profiles = await this.store.list();
+        if (profiles.some((entry) => entry.id === profile.id)) {
+            throw invalidInputError(MUTATION_FIELD.id, MUTATION_ERROR_REASON.duplicateProfileId(profile.id));
+        }
+        const nextProfiles = [...profiles, profile];
+        validateProfileRecords(nextProfiles);
+        await this.store.save(nextProfiles);
+        return profile;
+    }
+}
+class FileAgentConfigManager {
+    store;
+    agentConfigTypes;
+    constructor(store, agentConfigTypes) {
+        this.store = store;
+        this.agentConfigTypes = agentConfigTypes;
+    }
+    async list() {
+        return (await this.store.read()).agentConfigs;
+    }
+    async getSettings() {
+        return await this.store.read();
+    }
+    async add(record) {
+        const settings = await this.store.read();
+        if (settings.agentConfigs.some((agentConfig) => agentConfig.id === record.id)) {
+            throw invalidInputError(MUTATION_FIELD.id, MUTATION_ERROR_REASON.duplicateAgentConfigId(record.id));
+        }
+        validateAgentConfigMutationRecord(record, this.agentConfigTypes);
+        const nextSettings = {
+            ...settings,
+            agentConfigs: [...settings.agentConfigs, record],
+        };
+        validateAgentConfigSettings(nextSettings, this.agentConfigTypes);
+        await this.store.save(nextSettings);
+        return record;
+    }
+    async update(id, patch) {
+        const settings = await this.store.read();
+        const agentConfig = settings.agentConfigs.find((entry) => entry.id === id);
+        if (agentConfig === undefined) {
+            return null;
+        }
+        const nextAgentConfig = {
+            ...agentConfig,
+            ...(patch.enabled === undefined ? {} : { enabled: patch.enabled }),
+            ...(patch.payload === undefined ? {} : { payload: patch.payload }),
+        };
+        validateAgentConfigMutationRecord(nextAgentConfig, this.agentConfigTypes);
+        const agentConfigs = settings.agentConfigs.map((entry) => entry.id === id ? nextAgentConfig : entry);
+        const nextSettings = { ...settings, agentConfigs };
+        validateAgentConfigSettings(nextSettings, this.agentConfigTypes);
+        await this.store.save(nextSettings);
+        return nextAgentConfig;
+    }
+    async remove(id) {
+        const settings = await this.store.read();
+        const agentConfig = settings.agentConfigs.find((entry) => entry.id === id);
+        if (agentConfig === undefined) {
+            return null;
+        }
+        const nextSettings = {
+            ...settings,
+            agentConfigs: settings.agentConfigs.filter((entry) => entry.id !== id),
+        };
+        validateAgentConfigSettings(nextSettings, this.agentConfigTypes);
+        await this.store.save(nextSettings);
+        return agentConfig;
+    }
+    async reorder(ids) {
+        const settings = await this.store.read();
+        const agentConfigs = reorderRecords({
+            ids,
+            records: settings.agentConfigs,
+            idOf: (agentConfig) => agentConfig.id,
+            field: MUTATION_FIELD.agentConfigOrder,
+            duplicateReason: MUTATION_ERROR_REASON.duplicateReorderId,
+            missingReason: MUTATION_ERROR_REASON.missingAgentConfigId,
+            incompleteReason: MUTATION_ERROR_REASON.incompleteAgentConfigOrder,
+        });
+        const nextSettings = { ...settings, agentConfigs };
+        validateAgentConfigSettings(nextSettings, this.agentConfigTypes);
+        await this.store.save(nextSettings);
+        return agentConfigs;
+    }
+    async setAmbientBuiltinAuth(enabled) {
+        const settings = await this.store.read();
+        const nextSettings = {
+            ...settings,
+            ambientBuiltinAuth: { enabled },
+        };
+        validateAgentConfigSettings(nextSettings, this.agentConfigTypes);
+        await this.store.save(nextSettings);
+        return nextSettings;
+    }
+}
+class FileProfileStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async list() {
+        const raw = await readOptionalFile(this.filePath);
+        if (raw === null) {
+            return [];
+        }
+        return parseProfilesFile(this.filePath, raw).profiles;
+    }
+    async save(profiles) {
+        const file = {
+            version: AGENTS_CONFIG_FILE_VERSION,
+            profiles,
+        };
+        await writeJsonAtomically(this.filePath, file);
+    }
+}
+class FileAgentConfigSettingsStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async read() {
+        const raw = await readOptionalFile(this.filePath);
+        if (raw === null) {
+            return DEFAULT_AGENTS_CONFIG_AGENT_SETTINGS;
+        }
+        return parseAgentConfigSettingsFile(this.filePath, raw);
+    }
+    async save(settings) {
+        const file = {
+            version: AGENTS_CONFIG_FILE_VERSION,
+            ...settings,
+        };
+        await writeJsonAtomically(this.filePath, file);
+    }
+}
+export function openAgentsConfigStores(paths, agentConfigTypes) {
+    const profiles = new FileProfileStore(paths.profilesFile);
+    const agentConfigs = new FileAgentConfigSettingsStore(paths.agentConfigSettingsFile);
+    return {
+        paths,
+        profiles: new FileProfileManager(profiles),
+        agentConfigs: new FileAgentConfigManager(agentConfigs, agentConfigTypes),
+        fleetStateStore: fileFleetStore(paths.fleetStateFile),
+    };
+}
+export async function loadConfigData(home) {
+    return {
+        paths: home.paths,
+        profiles: await home.profiles.list(),
+        agentConfigs: await home.agentConfigs.getSettings(),
+    };
+}
+function validateProfileRecords(profiles) {
+    const result = profilesFileSchema.safeParse({
+        version: AGENTS_CONFIG_FILE_VERSION,
+        profiles,
+    });
+    if (!result.success) {
+        throw zodIssueInvalidInputError(result.error.issues[0]);
+    }
+}
+function validateAgentConfigMutationRecord(record, agentConfigTypes) {
+    throwAgentConfigValidationInputError(validateAgentConfig(record, agentConfigTypes), {
+        kind: MUTATION_FIELD.agentConfigKind,
+        payload: MUTATION_FIELD.agentConfigPayload,
+    });
+}
+function validateAgentConfigSettings(settings, agentConfigTypes) {
+    const result = agentConfigSettingsFileSchema.safeParse({
+        version: AGENTS_CONFIG_FILE_VERSION,
+        ...settings,
+    });
+    if (!result.success) {
+        throw zodIssueInvalidInputError(result.error.issues[0]);
+    }
+    validateAgentConfigSettingRows(settings, agentConfigTypes);
+}
+function validateAgentConfigSettingRows(settings, agentConfigTypes) {
+    for (const [index, record] of settings.agentConfigs.entries()) {
+        throwAgentConfigValidationInputError(validateAgentConfig(record, agentConfigTypes), {
+            kind: agentConfigField(index, MUTATION_FIELD.agentConfigKind),
+            payload: agentConfigField(index, MUTATION_FIELD.agentConfigPayload),
+        });
+    }
+}
+function throwAgentConfigValidationInputError(validation, field) {
+    if (validation.kind === AGENT_CONFIG_VALIDATION_RESULT.unknownKind) {
+        throw invalidInputError(field.kind, MUTATION_ERROR_REASON.unknownAgentConfigKind(validation.agentConfigKind));
+    }
+    if (validation.kind === AGENT_CONFIG_VALIDATION_RESULT.invalidPayload) {
+        throw invalidInputError(field.payload, MUTATION_ERROR_REASON.invalidAgentConfigPayload(validation.issues));
+    }
+}
+function agentConfigField(index, field) {
+    return formatFieldPath([MUTATION_FIELD.agentConfigs, index, field]);
+}
+function reorderRecords(input) {
+    if (input.ids.length !== input.records.length) {
+        throw invalidInputError(input.field, input.incompleteReason);
+    }
+    const recordsById = new Map(input.records.map((record) => [input.idOf(record), record]));
+    const seenIds = new Set();
+    const records = [];
+    for (const id of input.ids) {
+        if (seenIds.has(id)) {
+            throw invalidInputError(input.field, input.duplicateReason(id));
+        }
+        seenIds.add(id);
+        const record = recordsById.get(id);
+        if (record === undefined) {
+            throw invalidInputError(input.field, input.missingReason(id));
+        }
+        records.push(record);
+    }
+    return records;
+}
+function zodIssueInvalidInputError(issue) {
+    if (issue === undefined) {
+        return invalidInputError(FIELD_PATH.root, FILE_PARSE_ERROR_REASON.invalidFile);
+    }
+    return invalidInputError(formatFieldPath(issue.path), issue.message);
+}
+function invalidInputError(field, reason) {
+    return new AgentsConfigError({
+        code: AGENTS_CONFIG_ERROR_CODE.invalidInput,
+        message: `${field}: ${reason}`,
+        data: { field, reason },
+    });
+}
+async function readOptionalFile(filePath) {
+    try {
+        return await readFile(filePath, TEXT_ENCODING);
+    }
+    catch (error) {
+        if (isErrnoCode(error, NODE_ERRNO_CODE.missingFile)) {
+            return null;
+        }
+        throw error;
+    }
+}
+function parseProfilesFile(filePath, raw) {
+    return parseJsonFile(filePath, raw, profilesFileSchema);
+}
+function parseAgentConfigSettingsFile(filePath, raw) {
+    return parseJsonFile(filePath, raw, agentConfigSettingsFileSchema);
+}
+function parseJsonFile(filePath, raw, schema) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw invalidFileError({
+            filePath,
+            field: FIELD_PATH.root,
+            reason: error instanceof Error
+                ? error.message
+                : FILE_PARSE_ERROR_REASON.invalidJson,
+            cause: error,
+        });
+    }
+    const result = schema.safeParse(parsed);
+    if (result.success) {
+        return result.data;
+    }
+    const firstIssue = result.error.issues[0];
+    throw invalidFileError({
+        filePath,
+        field: firstIssue === undefined
+            ? FIELD_PATH.root
+            : formatFieldPath(firstIssue.path),
+        reason: firstIssue?.message ?? FILE_PARSE_ERROR_REASON.invalidFile,
+        cause: result.error,
+    });
+}
+function invalidFileError(input) {
+    return new AgentsConfigError({
+        code: AGENTS_CONFIG_ERROR_CODE.invalidFile,
+        message: `${input.filePath}:${input.field}: ${input.reason}`,
+        data: {
+            filePath: input.filePath,
+            field: input.field,
+            reason: input.reason,
+        },
+        cause: input.cause,
+    });
+}
+async function writeJsonAtomically(filePath, value) {
+    await mkdir(path.dirname(filePath), {
+        recursive: true,
+        mode: PRIVATE_DIRECTORY_MODE,
+    });
+    const tempPath = [
+        filePath,
+        String(process.pid),
+        String(Date.now()),
+        TEMP_FILE_SUFFIX,
+    ].join(TEMP_FILE_PATH_SEPARATOR);
+    await writeFile(tempPath, `${JSON.stringify(value, null, JSON_INDENT_SPACES)}${TRAILING_NEWLINE}`, {
+        encoding: TEXT_ENCODING,
+        mode: PRIVATE_FILE_MODE,
+    });
+    await rename(tempPath, filePath);
+}

package/dist/config/support.d.ts

@@ -0,0 +1,14 @@
+export declare const ZOD_ISSUE_CODE: {
+    readonly custom: "custom";
+};
+export declare const FIELD_PATH: {
+    readonly root: "$";
+    readonly separator: ".";
+};
+export declare const NODE_ERRNO_CODE: {
+    readonly missingFile: "ENOENT";
+};
+export declare function readNonBlankEnvValue(env: Readonly<Record<string, string | undefined>>, name: string): string | null;
+export declare function formatFieldPath(pathParts: readonly PropertyKey[]): string;
+export declare function isErrnoCode(error: unknown, code: string): boolean;
+//# sourceMappingURL=support.d.ts.map

package/dist/config/support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"support.d.ts","sourceRoot":"","sources":["../../src/config/support.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc;;CAEjB,CAAC;AAEX,eAAO,MAAM,UAAU;;;CAGb,CAAC;AAEX,eAAO,MAAM,eAAe;;CAElB,CAAC;AAMX,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EACjD,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,IAAI,CAGf;AAMD,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAKzE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAOjE"}

package/dist/config/support.js

@@ -0,0 +1,32 @@
+export const ZOD_ISSUE_CODE = {
+    custom: "custom",
+};
+export const FIELD_PATH = {
+    root: "$",
+    separator: ".",
+};
+export const NODE_ERRNO_CODE = {
+    missingFile: "ENOENT",
+};
+const NODE_ERROR_FIELD = {
+    code: "code",
+};
+export function readNonBlankEnvValue(env, name) {
+    const value = env[name];
+    return isNonBlankString(value) ? value : null;
+}
+function isNonBlankString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+export function formatFieldPath(pathParts) {
+    if (pathParts.length === 0) {
+        return FIELD_PATH.root;
+    }
+    return pathParts.map(String).join(FIELD_PATH.separator);
+}
+export function isErrnoCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        NODE_ERROR_FIELD.code in error &&
+        Reflect.get(error, NODE_ERROR_FIELD.code) === code);
+}

package/dist/config/values.d.ts

@@ -0,0 +1,21 @@
+export { BUILTIN_AGENT_ID } from "../agents/builtin.js";
+export declare const AGENTS_CONFIG_FILE: {
+    readonly profiles: "auth-profiles.json";
+    readonly agentConfigSettings: "agent-settings.json";
+    readonly fleetState: "fleet-state.json";
+};
+export declare const AGENT_CONFIG_KIND: {
+    readonly codex: import("./ids.js").AgentConfigKind;
+    readonly claude: import("./ids.js").AgentConfigKind;
+    readonly openaiCompatible: import("./ids.js").AgentConfigKind;
+};
+export declare const DEFAULT_AGENT_CONFIG_ID: {
+    readonly codex: import("./ids.js").AgentConfigId;
+    readonly claude: import("./ids.js").AgentConfigId;
+};
+export declare const CANDIDATE_SOURCE_KIND: {
+    readonly profile: "profile";
+    readonly ambient: "ambient";
+    readonly configured: "configured";
+};
+//# sourceMappingURL=values.d.ts.map

package/dist/config/values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/config/values.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,eAAO,MAAM,kBAAkB;;;;CAIrB,CAAC;AAEX,eAAO,MAAM,iBAAiB;;;;CAIpB,CAAC;AAEX,eAAO,MAAM,uBAAuB;;;CAG1B,CAAC;AAEX,eAAO,MAAM,qBAAqB;;;;CAIxB,CAAC"}

package/dist/config/values.js

@@ -0,0 +1,22 @@
+import { BUILTIN_AGENT_ID } from "../agents/builtin.js";
+import { agentConfigId, agentConfigKind } from "./ids.js";
+export { BUILTIN_AGENT_ID } from "../agents/builtin.js";
+export const AGENTS_CONFIG_FILE = {
+    profiles: "auth-profiles.json",
+    agentConfigSettings: "agent-settings.json",
+    fleetState: "fleet-state.json",
+};
+export const AGENT_CONFIG_KIND = {
+    codex: agentConfigKind(BUILTIN_AGENT_ID.codex),
+    claude: agentConfigKind(BUILTIN_AGENT_ID.claude),
+    openaiCompatible: agentConfigKind("openai-compatible"),
+};
+export const DEFAULT_AGENT_CONFIG_ID = {
+    codex: agentConfigId(BUILTIN_AGENT_ID.codex),
+    claude: agentConfigId(BUILTIN_AGENT_ID.claude),
+};
+export const CANDIDATE_SOURCE_KIND = {
+    profile: "profile",
+    ambient: "ambient",
+    configured: "configured",
+};

package/dist/config/xdg.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A convention-neutral config preset for general OSS consumers: resolve
+ * the config root from the XDG Base Directory spec
+ * (`$XDG_CONFIG_HOME/<appName>/agents`, defaulting to
+ * `<homeDir>/.config/<appName>/agents`). It owns no secret-storage
+ * policy — the app supplies its own `secretResolvers` (e.g.
+ * `keyringResolver` from `/keyring`) if it needs one. Any consumer can
+ * write its own convention module (paths + keyring) as a plain instance of
+ * this same shape; this preset is just the general default.
+ */
+import type { OpenAgentsConfigOptions } from "./config.js";
+export declare const XDG_CONFIG_HOME_ENV_VAR = "XDG_CONFIG_HOME";
+export type XdgAgentsConfigInput = {
+    readonly appName: string;
+    readonly homeDir: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+};
+export declare function resolveXdgAgentsConfigOptions(input: XdgAgentsConfigInput): OpenAgentsConfigOptions;
+export declare function resolveXdgAgentsConfigRootDir(input: XdgAgentsConfigInput): string;
+//# sourceMappingURL=xdg.d.ts.map

package/dist/config/xdg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xdg.d.ts","sourceRoot":"","sources":["../../src/config/xdg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAG3D,eAAO,MAAM,uBAAuB,oBAAoB,CAAC;AAIzD,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CAC5D,CAAC;AAEF,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,oBAAoB,GAC1B,uBAAuB,CAEzB;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,oBAAoB,GAC1B,MAAM,CAKR"}

package/dist/config/xdg.js

@@ -0,0 +1,23 @@
+/**
+ * A convention-neutral config preset for general OSS consumers: resolve
+ * the config root from the XDG Base Directory spec
+ * (`$XDG_CONFIG_HOME/<appName>/agents`, defaulting to
+ * `<homeDir>/.config/<appName>/agents`). It owns no secret-storage
+ * policy — the app supplies its own `secretResolvers` (e.g.
+ * `keyringResolver` from `/keyring`) if it needs one. Any consumer can
+ * write its own convention module (paths + keyring) as a plain instance of
+ * this same shape; this preset is just the general default.
+ */
+import path from "node:path";
+import { readNonBlankEnvValue } from "./support.js";
+export const XDG_CONFIG_HOME_ENV_VAR = "XDG_CONFIG_HOME";
+const DEFAULT_XDG_CONFIG_DIRECTORY = ".config";
+const AGENTS_CONFIG_SUBDIRECTORY = "agents";
+export function resolveXdgAgentsConfigOptions(input) {
+    return { rootDir: resolveXdgAgentsConfigRootDir(input) };
+}
+export function resolveXdgAgentsConfigRootDir(input) {
+    const base = readNonBlankEnvValue(input.env, XDG_CONFIG_HOME_ENV_VAR) ??
+        path.join(input.homeDir, DEFAULT_XDG_CONFIG_DIRECTORY);
+    return path.join(base, input.appName, AGENTS_CONFIG_SUBDIRECTORY);
+}

package/dist/core/async-queue.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Unbounded push-based async queue backing exec chunk streams and the
+ * run-handle event broadcast. Internal only.
+ */
+export declare class AsyncQueue<T> implements AsyncIterable<T> {
+    private readonly buffered;
+    private readonly waiters;
+    private ended;
+    push(value: T): void;
+    end(): void;
+    private next;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+//# sourceMappingURL=async-queue.d.ts.map

package/dist/core/async-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-queue.d.ts","sourceRoot":"","sources":["../../src/core/async-queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,UAAU,CAAC,CAAC,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkD;IAC1E,OAAO,CAAC,KAAK,CAAS;IAEtB,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAYpB,GAAG,IAAI,IAAI;IAUX,OAAO,CAAC,IAAI;IAaZ,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;CAK3C"}

package/dist/core/async-queue.js

@@ -0,0 +1,46 @@
+/**
+ * Unbounded push-based async queue backing exec chunk streams and the
+ * run-handle event broadcast. Internal only.
+ */
+export class AsyncQueue {
+    buffered = [];
+    waiters = [];
+    ended = false;
+    push(value) {
+        if (this.ended) {
+            return;
+        }
+        const waiter = this.waiters.shift();
+        if (waiter === undefined) {
+            this.buffered.push(value);
+            return;
+        }
+        waiter({ value, done: false });
+    }
+    end() {
+        if (this.ended) {
+            return;
+        }
+        this.ended = true;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter({ value: undefined, done: true });
+        }
+    }
+    next() {
+        const value = this.buffered.shift();
+        if (value !== undefined) {
+            return Promise.resolve({ value, done: false });
+        }
+        if (this.ended) {
+            return Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => this.next(),
+        };
+    }
+}

package/dist/core/env.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Env mutation as data (design A8): activating one auth mechanism must be
+ * able to clear competing variables, so a patch carries both directions.
+ */
+export type EnvPatch = {
+    set: Record<string, string>;
+    unset: string[];
+};
+export declare const EMPTY_ENV_PATCH: EnvPatch;
+export declare function applyEnvPatch(env: Record<string, string>, patch: EnvPatch): Record<string, string>;
+export declare function mergeEnvPatches(first: EnvPatch, second: EnvPatch): EnvPatch;
+/**
+ * Snapshot `process.env` as a defined-only `Record<string, string>` — the
+ * `baseEnv` shape `createAgentRuntime` and `runAgent` expect. Exposed so
+ * callers stop reaching for `process.env as Record<string, string>`, which
+ * lies about the `undefined` values Node keeps on the object.
+ */
+export declare function processEnv(): Record<string, string>;
+//# sourceMappingURL=env.d.ts.map

package/dist/core/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/core/env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAGF,eAAO,MAAM,eAAe,EAAE,QAAgD,CAAC;AAI/E,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,KAAK,EAAE,QAAQ,GACd,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAK3E;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQnD"}