@alpacakit/agents-conventions 0.1.0-beta.36 → 0.1.0-beta.39

package/dist/index.js

@@ -1,59 +1,20 @@
 /**
- * AlpacaLoop-family conventions for `@alpacakit/agents` machine-local
- * config. This lives OUTSIDE the neutral `@alpacakit/agents` package on
- * purpose: it encodes AlpacaLoop-specific paths, keyring service names, and
- * the managed-home layout that no general OSS consumer needs. It builds on
- * the agents package's PUBLIC API only, so it is a plain consumer — the
- * same shape any third party would write for their own family convention.
+ * AlpacaKit-family conventions for `@alpacakit/agents` machine-local config.
+ * This lives OUTSIDE the neutral `@alpacakit/agents` package on purpose: it
+ * encodes the family's shared home, keyring service names, managed-home
+ * layout, and the ORDER and FAILURE POLICY of registering an agent — none of
+ * which a general OSS consumer needs. It builds on the agents package's
+ * PUBLIC API only, so it is a plain consumer: the same shape any third party
+ * would write for their own family convention.
  *
- * Not published (`private`): the public source doubles as the worked
- * example, without adding org policy to the npm surface.
+ * Products call the procedures here and print the result; they never re-decide
+ * the order or the failure policy. The `agent` command surface that mounts
+ * them lives on `./cli` (data only), so importing the procedures never pulls
+ * in `@alpacakit/channels`.
  */
-import path from "node:path";
-import { keyringResolver } from "@alpacakit/agents/keyring";
-export const ALPACA_LOOP_AGENTS_CONFIG_ENV_VAR = "ALPACA_AGENTS_HOME";
-export const ALPACA_LOOP_AGENTS_CONFIG_DIRECTORY = ".alpaca/agents";
-export const ALPACA_LOOP_AGENTS_CONFIG_KEYRING_SERVICE = "alpacaloop.agents-home";
-export const ALPACA_LOOP_AGENTS_CONFIG_KEYRING_RESOLVER = "agents-home-keyring";
-const ALPACA_LOOP_AGENTS_CONFIG_MANAGED_HOMES_DIRECTORY = "managed-homes";
-const ALPACA_LOOP_AGENTS_CONFIG_KEYRING_ACCOUNT = {
-    prefix: "profile",
-    apiKeySuffix: "api-key",
-    separator: ":",
-};
-export function resolveAgentsConfigOptions(input) {
-    return {
-        rootDir: resolveAgentsConfigRootDir(input),
-        secretResolvers: [createKeyringResolverEntry()],
-    };
-}
-export function createKeyringSecretRef(profileId) {
-    return {
-        resolver: ALPACA_LOOP_AGENTS_CONFIG_KEYRING_RESOLVER,
-        id: [
-            ALPACA_LOOP_AGENTS_CONFIG_KEYRING_ACCOUNT.prefix,
-            profileId,
-            ALPACA_LOOP_AGENTS_CONFIG_KEYRING_ACCOUNT.apiKeySuffix,
-        ].join(ALPACA_LOOP_AGENTS_CONFIG_KEYRING_ACCOUNT.separator),
-    };
-}
-export function resolveManagedHomePath(input) {
-    return path.join(input.rootDir, ALPACA_LOOP_AGENTS_CONFIG_MANAGED_HOMES_DIRECTORY, input.profileId);
-}
-function resolveAgentsConfigRootDir(input) {
-    return (readNonBlankEnvValue(input.env, ALPACA_LOOP_AGENTS_CONFIG_ENV_VAR) ??
-        path.join(input.homeDir, ALPACA_LOOP_AGENTS_CONFIG_DIRECTORY));
-}
-function createKeyringResolverEntry() {
-    return {
-        name: ALPACA_LOOP_AGENTS_CONFIG_KEYRING_RESOLVER,
-        resolver: keyringResolver({
-            service: ALPACA_LOOP_AGENTS_CONFIG_KEYRING_SERVICE,
-        }),
-    };
-}
-/** Inlined from the agents package's internal env helper (not exported). */
-function readNonBlankEnvValue(env, name) {
-    const value = env[name];
-    return typeof value === "string" && value.trim().length > 0 ? value : null;
-}
+export { createRuntimeFactory, listAgentsHome, openAgentsHome, } from "./home.js";
+export { AGENTS_HOME_RECORD_NAME_MAX_LENGTH, AGENTS_HOME_RECORD_NAME_PATTERN, AGENTS_HOME_RECORD_NAME_RULE, INVALID_NAME_RESULT_KIND, isAgentsHomeRecordName, rejectInvalidName, } from "./names.js";
+export { createKeyringSecretRef, isManagedHomePath, resolveAgentsConfigOptions, resolveAgentsHome, resolveManagedHomePath, } from "./paths.js";
+export { ADD_AGENT_CONFIG_RESULT, ADD_API_KEY_PROFILE_RESULT, addAgentConfig, addApiKeyProfile, LOGIN_MANAGED_HOME_RESULT, loginManagedHome, } from "./register.js";
+export { REMOVE_AGENTS_HOME_ENTRY_RESULT, removeAgentsHomeEntry, } from "./remove.js";
+export { AGENT_ADD_KIND, AGENTS_HOME_DIRECTORY, AGENTS_HOME_ENV_VAR, AGENTS_KEYRING_ACCOUNT, AGENTS_KEYRING_RESOLVER, AGENTS_KEYRING_SERVICE, AGENTS_MANAGED_HOMES_DIRECTORY, } from "./values.js";

package/dist/names.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The grammar of a record name in the shared home — profile ids and agent
+ * config ids — spelled ONCE.
+ *
+ * A record name is not free text: it becomes a path segment under
+ * `managed-homes/` and a segment of a keychain account
+ * (`profile:<name>:api-key`). An unconstrained name therefore decides where
+ * this package writes and what it deletes — `../../../escape` would put a
+ * login home outside the shared home and make `agent remove` delete a tree
+ * that is not ours. Constraining the vocabulary is the fix; checking for
+ * `..` at each use site is not, because the next use site forgets.
+ *
+ * This narrows, and so satisfies, the agents package's own id rule
+ * (non-empty, non-blank).
+ */
+/** Lowercase, starts with a letter or digit, no separators of any kind. */
+export declare const AGENTS_HOME_RECORD_NAME_PATTERN: RegExp;
+export declare const AGENTS_HOME_RECORD_NAME_MAX_LENGTH = 64;
+/**
+ * The rule in words, carried on the rejection so a product can tell the
+ * operator what to type without restating the grammar.
+ */
+export declare const AGENTS_HOME_RECORD_NAME_RULE = "A name must be 1 to 64 characters of lowercase letters, digits, \".\", \"-\" or \"_\", and must start with a letter or digit.";
+export declare const INVALID_NAME_RESULT_KIND: "invalid_name";
+/** Shared by every procedure that takes a record name (I4: expected, not a fault). */
+export type InvalidNameResult = {
+    readonly kind: typeof INVALID_NAME_RESULT_KIND;
+    readonly name: string;
+    readonly rule: string;
+};
+export declare function isAgentsHomeRecordName(value: string): boolean;
+/**
+ * `null` when the name is usable. Procedures call this at their entry so a
+ * caller that reaches them without going through the CLI codec gets the same
+ * answer the CLI would have given.
+ */
+export declare function rejectInvalidName(name: string): InvalidNameResult | null;
+//# sourceMappingURL=names.d.ts.map

package/dist/names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../src/names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,+BAA+B,QAAiC,CAAC;AAE9E,eAAO,MAAM,kCAAkC,KAAK,CAAC;AAErD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,kIAA+J,CAAC;AAEzM,eAAO,MAAM,wBAAwB,EAAG,cAAuB,CAAC;AAEhE,sFAAsF;AACtF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,wBAAwB,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAQxE"}

package/dist/names.js

@@ -0,0 +1,41 @@
+/**
+ * The grammar of a record name in the shared home — profile ids and agent
+ * config ids — spelled ONCE.
+ *
+ * A record name is not free text: it becomes a path segment under
+ * `managed-homes/` and a segment of a keychain account
+ * (`profile:<name>:api-key`). An unconstrained name therefore decides where
+ * this package writes and what it deletes — `../../../escape` would put a
+ * login home outside the shared home and make `agent remove` delete a tree
+ * that is not ours. Constraining the vocabulary is the fix; checking for
+ * `..` at each use site is not, because the next use site forgets.
+ *
+ * This narrows, and so satisfies, the agents package's own id rule
+ * (non-empty, non-blank).
+ */
+/** Lowercase, starts with a letter or digit, no separators of any kind. */
+export const AGENTS_HOME_RECORD_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/u;
+export const AGENTS_HOME_RECORD_NAME_MAX_LENGTH = 64;
+/**
+ * The rule in words, carried on the rejection so a product can tell the
+ * operator what to type without restating the grammar.
+ */
+export const AGENTS_HOME_RECORD_NAME_RULE = `A name must be 1 to ${AGENTS_HOME_RECORD_NAME_MAX_LENGTH} characters of lowercase letters, digits, ".", "-" or "_", and must start with a letter or digit.`;
+export const INVALID_NAME_RESULT_KIND = "invalid_name";
+export function isAgentsHomeRecordName(value) {
+    return AGENTS_HOME_RECORD_NAME_PATTERN.test(value);
+}
+/**
+ * `null` when the name is usable. Procedures call this at their entry so a
+ * caller that reaches them without going through the CLI codec gets the same
+ * answer the CLI would have given.
+ */
+export function rejectInvalidName(name) {
+    return isAgentsHomeRecordName(name)
+        ? null
+        : {
+            kind: INVALID_NAME_RESULT_KIND,
+            name,
+            rule: AGENTS_HOME_RECORD_NAME_RULE,
+        };
+}

package/dist/paths.d.ts

@@ -0,0 +1,41 @@
+import type { SecretRef } from "@alpacakit/agents";
+import type { OpenAgentsConfigOptions } from "@alpacakit/agents/config";
+/**
+ * What every family procedure starts from: the machine's home directory and
+ * its environment. Nothing here reads `os.homedir()` or `process.env` — the
+ * caller owns both, so a test can point the whole family at a temp dir.
+ */
+export type AgentsConfigOptionsInput = {
+    readonly homeDir: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+};
+export type ManagedHomePathInput = {
+    readonly rootDir: string;
+    readonly profileId: string;
+};
+export declare function resolveAgentsConfigOptions(input: AgentsConfigOptionsInput): OpenAgentsConfigOptions;
+/** The shared home every family product opens. */
+export declare function resolveAgentsHome(input: AgentsConfigOptionsInput): string;
+export declare function createKeyringSecretRef(profileId: string): SecretRef;
+/**
+ * The ONE place a managed-home path is built, and therefore the one place the
+ * invariant belongs: the result is always a direct child of
+ * `<agents home>/managed-homes`. Names are validated at every procedure's
+ * entry (`rejectInvalidName`), so a name that could escape means a caller
+ * bypassed that — a programming fault, not an operator's mistake, and it
+ * throws rather than quietly writing outside the shared home.
+ */
+export declare function resolveManagedHomePath(input: ManagedHomePathInput): string;
+/**
+ * Whether `path` is a login home this package created under the shared home,
+ * and may therefore delete. A home the operator pointed at themselves is
+ * theirs, so `agent remove` leaves it alone — and so is anything a name that
+ * cannot form a managed-home path could point at, which is why this answers
+ * `false` where `resolveManagedHomePath` throws.
+ */
+export declare function isManagedHomePath(input: {
+    readonly rootDir: string;
+    readonly profileId: string;
+    readonly path: string;
+}): boolean;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAEV,uBAAuB,EACxB,MAAM,0BAA0B,CAAC;AAelC;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,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,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,wBAAwB,GAC9B,uBAAuB,CAKzB;AAED,kDAAkD;AAClD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,CAKzE;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CASnE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAQ1E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAGV"}

package/dist/paths.js

@@ -0,0 +1,72 @@
+import path from "node:path";
+import { keyringResolver } from "@alpacakit/core/keyring";
+import { AGENTS_HOME_RECORD_NAME_RULE, isAgentsHomeRecordName, } from "./names.js";
+import { AGENTS_HOME_DIRECTORY, AGENTS_HOME_ENV_VAR, AGENTS_KEYRING_ACCOUNT, AGENTS_KEYRING_RESOLVER, AGENTS_KEYRING_SERVICE, AGENTS_MANAGED_HOMES_DIRECTORY, } from "./values.js";
+export function resolveAgentsConfigOptions(input) {
+    return {
+        rootDir: resolveAgentsHome(input),
+        secretResolvers: [createKeyringResolverEntry()],
+    };
+}
+/** The shared home every family product opens. */
+export function resolveAgentsHome(input) {
+    return (readNonBlankEnvValue(input.env, AGENTS_HOME_ENV_VAR) ??
+        path.join(input.homeDir, AGENTS_HOME_DIRECTORY));
+}
+export function createKeyringSecretRef(profileId) {
+    return {
+        resolver: AGENTS_KEYRING_RESOLVER,
+        id: [
+            AGENTS_KEYRING_ACCOUNT.prefix,
+            profileId,
+            AGENTS_KEYRING_ACCOUNT.apiKeySuffix,
+        ].join(AGENTS_KEYRING_ACCOUNT.separator),
+    };
+}
+/**
+ * The ONE place a managed-home path is built, and therefore the one place the
+ * invariant belongs: the result is always a direct child of
+ * `<agents home>/managed-homes`. Names are validated at every procedure's
+ * entry (`rejectInvalidName`), so a name that could escape means a caller
+ * bypassed that — a programming fault, not an operator's mistake, and it
+ * throws rather than quietly writing outside the shared home.
+ */
+export function resolveManagedHomePath(input) {
+    const resolved = managedHomePathOrNull(input);
+    if (resolved === null) {
+        throw new Error(`"${input.profileId}" is not a usable managed-home name: ${AGENTS_HOME_RECORD_NAME_RULE}`);
+    }
+    return resolved;
+}
+/**
+ * Whether `path` is a login home this package created under the shared home,
+ * and may therefore delete. A home the operator pointed at themselves is
+ * theirs, so `agent remove` leaves it alone — and so is anything a name that
+ * cannot form a managed-home path could point at, which is why this answers
+ * `false` where `resolveManagedHomePath` throws.
+ */
+export function isManagedHomePath(input) {
+    const managed = managedHomePathOrNull(input);
+    return managed !== null && path.resolve(input.path) === managed;
+}
+/** `null` when the name would not land directly under `managed-homes`. */
+function managedHomePathOrNull(input) {
+    const parent = path.resolve(input.rootDir, AGENTS_MANAGED_HOMES_DIRECTORY);
+    const resolved = path.resolve(parent, input.profileId);
+    const containedSegment = path.dirname(resolved) === parent &&
+        path.basename(resolved) === input.profileId;
+    return isAgentsHomeRecordName(input.profileId) && containedSegment
+        ? resolved
+        : null;
+}
+function createKeyringResolverEntry() {
+    return {
+        name: AGENTS_KEYRING_RESOLVER,
+        resolver: keyringResolver({ service: AGENTS_KEYRING_SERVICE }),
+    };
+}
+/** Inlined from the agents package's internal env helper (not exported). */
+function readNonBlankEnvValue(env, name) {
+    const value = env[name];
+    return typeof value === "string" && value.trim().length > 0 ? value : null;
+}

package/dist/register.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The three ways an agent enters the shared home — a browser sign-in into a
+ * managed home, a pasted credential, or a plain OpenAI-compatible endpoint.
+ * Each owns its ORDER and its FAILURE POLICY, which is the whole reason these
+ * live here and not in an app: a half-registered credential must not depend
+ * on which product ran the command.
+ */
+import { type LoginEvent, type LoginMethod } from "@alpacakit/agents";
+import type { AgentConfig, OpenAiCompatibleEngineKind, ProfileRecord } from "@alpacakit/agents/config";
+import { type AgentsHomeInput } from "./home.js";
+import { type InvalidNameResult } from "./names.js";
+import { AGENT_ADD_KIND } from "./values.js";
+export declare const LOGIN_MANAGED_HOME_RESULT: {
+    readonly registered: "registered";
+    readonly profileExists: "profile_exists";
+    readonly unknownAgent: "unknown_agent";
+    readonly unsupported: "unsupported";
+    readonly loginFailed: "login_failed";
+};
+export declare const ADD_API_KEY_PROFILE_RESULT: {
+    readonly registered: "registered";
+    readonly profileExists: "profile_exists";
+    readonly emptyKey: "empty_key";
+};
+export declare const ADD_AGENT_CONFIG_RESULT: {
+    readonly added: "added";
+    readonly exists: "exists";
+};
+export type LoginManagedHomeInput = AgentsHomeInput & {
+    readonly profileId: string;
+    readonly agentId: string;
+    readonly method: LoginMethod;
+    readonly signal?: AbortSignal;
+    readonly onEvent?: (event: LoginEvent) => void;
+};
+export type LoginManagedHomeResult = {
+    readonly kind: typeof LOGIN_MANAGED_HOME_RESULT.registered;
+    readonly profile: ProfileRecord;
+    readonly managedHome: string;
+} | {
+    readonly kind: typeof LOGIN_MANAGED_HOME_RESULT.profileExists;
+    readonly profileId: string;
+} | {
+    /** No agent config in this home projects that id — nothing to sign in to. */
+    readonly kind: typeof LOGIN_MANAGED_HOME_RESULT.unknownAgent;
+    readonly agentId: string;
+    readonly known: readonly string[];
+} | {
+    /** The agent is here; it just does not offer that sign-in method. */
+    readonly kind: typeof LOGIN_MANAGED_HOME_RESULT.unsupported;
+    readonly agentId: string;
+    readonly method: LoginMethod;
+    readonly supported: readonly LoginMethod[];
+} | {
+    readonly kind: typeof LOGIN_MANAGED_HOME_RESULT.loginFailed;
+    readonly detail: string;
+    readonly managedHome: string;
+} | InvalidNameResult;
+export type AddApiKeyProfileInput = AgentsHomeInput & {
+    readonly profileId: string;
+    readonly agentId: string;
+    readonly apiKey: string;
+};
+export type AddApiKeyProfileResult = {
+    readonly kind: typeof ADD_API_KEY_PROFILE_RESULT.registered;
+    readonly profile: ProfileRecord;
+} | {
+    readonly kind: typeof ADD_API_KEY_PROFILE_RESULT.profileExists;
+    readonly profileId: string;
+} | {
+    readonly kind: typeof ADD_API_KEY_PROFILE_RESULT.emptyKey;
+    readonly profileId: string;
+} | InvalidNameResult;
+/**
+ * One request shape per addable kind, discriminated by `kind` — the same
+ * discriminator `agent add --kind` carries, so the CLI projection IS this
+ * input. A new kind is a new member and a new row in the builder record.
+ */
+export type OpenAiCompatibleAgentConfigRequest = {
+    readonly kind: typeof AGENT_ADD_KIND.openaiCompatible;
+    readonly id: string;
+    readonly baseUrl: string;
+    readonly model: string;
+    /** Env var holding the key; stored as a `${VAR}` template, never the secret (A9). */
+    readonly apiKeyEnv?: string;
+    readonly engine?: OpenAiCompatibleEngineKind;
+};
+export type AgentConfigRequest = OpenAiCompatibleAgentConfigRequest;
+export type AddAgentConfigInput = AgentsHomeInput & AgentConfigRequest;
+export type AddAgentConfigResult = {
+    readonly kind: typeof ADD_AGENT_CONFIG_RESULT.added;
+    readonly agentConfig: AgentConfig;
+} | {
+    readonly kind: typeof ADD_AGENT_CONFIG_RESULT.exists;
+    readonly id: string;
+} | InvalidNameResult;
+/**
+ * Sign in with the agent's own CLI into a home this package owns, then record
+ * it. A failed sign-in leaves the directory in place — a device flow that
+ * timed out has already written state the next attempt continues from — but
+ * NEVER writes the profile, so the home never points at a home that cannot
+ * authenticate. A sign-in that succeeds and then cannot be recorded is a
+ * fault, not a result: silently discarding a completed browser flow would
+ * leave a live credential nobody knows about.
+ */
+export declare function loginManagedHome(input: LoginManagedHomeInput): Promise<LoginManagedHomeResult>;
+/**
+ * Store the key in the family keychain, then reference it from the home. If
+ * the reference cannot be written the stored secret is removed again, so a
+ * failed `credential add` never leaves an orphaned key in the operator's
+ * keychain that no command can ever name.
+ *
+ * A blank key is rejected before the keychain is touched: it is the operator's
+ * mistake (an empty paste, an empty pipe), not a keychain failure, so it comes
+ * back as a result and leaves nothing behind. The key is stored trimmed —
+ * `echo "sk-…" | … --stdin` otherwise saves a trailing newline that every
+ * later request sends to the provider.
+ */
+export declare function addApiKeyProfile(input: AddApiKeyProfileInput): Promise<AddApiKeyProfileResult>;
+/** Add an agent of the requested kind. `input.kind` is the discriminator. */
+export declare function addAgentConfig(input: AddAgentConfigInput): Promise<AddAgentConfigResult>;
+//# sourceMappingURL=register.d.ts.map

package/dist/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"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"}

package/dist/register.js

@@ -0,0 +1,212 @@
+/**
+ * The three ways an agent enters the shared home — a browser sign-in into a
+ * managed home, a pasted credential, or a plain OpenAI-compatible endpoint.
+ * Each owns its ORDER and its FAILURE POLICY, which is the whole reason these
+ * live here and not in an app: a half-registered credential must not depend
+ * on which product ran the command.
+ */
+import { mkdir } from "node:fs/promises";
+import { isAgentError, } from "@alpacakit/agents";
+import { openAiCompatibleAgentConfig } from "@alpacakit/agents/config";
+import { createRuntimeFactory, openAgentsHome, } from "./home.js";
+import { rejectInvalidName } from "./names.js";
+import { createKeyringSecretRef, resolveManagedHomePath } from "./paths.js";
+import { AGENT_ADD_KIND } from "./values.js";
+const PRIVATE_DIRECTORY_MODE = 0o700;
+const REGISTER_FAULT_MESSAGE = {
+    loginNotRegistered: (profileId, managedHome) => `Sign-in succeeded into "${managedHome}" but profile "${profileId}" could not be registered. The credential is on disk and unreferenced; fix the agents home and run the same login again.`,
+};
+export const LOGIN_MANAGED_HOME_RESULT = {
+    registered: "registered",
+    profileExists: "profile_exists",
+    unknownAgent: "unknown_agent",
+    unsupported: "unsupported",
+    loginFailed: "login_failed",
+};
+export const ADD_API_KEY_PROFILE_RESULT = {
+    registered: "registered",
+    profileExists: "profile_exists",
+    emptyKey: "empty_key",
+};
+export const ADD_AGENT_CONFIG_RESULT = {
+    added: "added",
+    exists: "exists",
+};
+/**
+ * Sign in with the agent's own CLI into a home this package owns, then record
+ * it. A failed sign-in leaves the directory in place — a device flow that
+ * timed out has already written state the next attempt continues from — but
+ * NEVER writes the profile, so the home never points at a home that cannot
+ * authenticate. A sign-in that succeeds and then cannot be recorded is a
+ * fault, not a result: silently discarding a completed browser flow would
+ * leave a live credential nobody knows about.
+ */
+export async function loginManagedHome(input) {
+    const invalidName = rejectInvalidName(input.profileId);
+    if (invalidName !== null) {
+        return invalidName;
+    }
+    const home = openAgentsHome(input);
+    if (await findProfile(home.config, input.profileId)) {
+        return {
+            kind: LOGIN_MANAGED_HOME_RESULT.profileExists,
+            profileId: input.profileId,
+        };
+    }
+    const runtimes = createRuntimeFactory(home, await home.config.loadRuntimeConfig());
+    const agents = runtimes.ambient.agents();
+    const agent = agents.find((candidate) => candidate.id === input.agentId);
+    // Two different problems with two different fixes: an id this home does not
+    // have (add or enable the agent config) versus a method this agent's CLI
+    // does not offer (use another method). Collapsing them would send the
+    // operator looking in the wrong place.
+    if (agent === undefined) {
+        return {
+            kind: LOGIN_MANAGED_HOME_RESULT.unknownAgent,
+            agentId: input.agentId,
+            known: agents.map((candidate) => candidate.id),
+        };
+    }
+    const login = agent.login;
+    if (login === null || !login.supports(input.method)) {
+        return {
+            kind: LOGIN_MANAGED_HOME_RESULT.unsupported,
+            agentId: input.agentId,
+            method: input.method,
+            supported: login?.methods() ?? [],
+        };
+    }
+    const managedHome = resolveManagedHomePath({
+        rootDir: home.agentsHome,
+        profileId: input.profileId,
+    });
+    await mkdir(managedHome, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });
+    const request = {
+        method: input.method,
+        homeDir: managedHome,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    };
+    const handle = login.start(request, home.location);
+    const drained = drainLoginEvents(handle.events, input.onEvent);
+    try {
+        await handle.result;
+    }
+    catch (thrown) {
+        await drained;
+        if (!isAgentError(thrown)) {
+            throw thrown;
+        }
+        return {
+            kind: LOGIN_MANAGED_HOME_RESULT.loginFailed,
+            detail: thrown.message,
+            managedHome,
+        };
+    }
+    await drained;
+    let profile;
+    try {
+        profile = await home.config.profiles.addHomeDir({
+            id: input.profileId,
+            agentId: input.agentId,
+            path: managedHome,
+        });
+    }
+    catch (cause) {
+        throw new Error(REGISTER_FAULT_MESSAGE.loginNotRegistered(input.profileId, managedHome), { cause });
+    }
+    return { kind: LOGIN_MANAGED_HOME_RESULT.registered, profile, managedHome };
+}
+/**
+ * Store the key in the family keychain, then reference it from the home. If
+ * the reference cannot be written the stored secret is removed again, so a
+ * failed `credential add` never leaves an orphaned key in the operator's
+ * keychain that no command can ever name.
+ *
+ * A blank key is rejected before the keychain is touched: it is the operator's
+ * mistake (an empty paste, an empty pipe), not a keychain failure, so it comes
+ * back as a result and leaves nothing behind. The key is stored trimmed —
+ * `echo "sk-…" | … --stdin` otherwise saves a trailing newline that every
+ * later request sends to the provider.
+ */
+export async function addApiKeyProfile(input) {
+    const invalidName = rejectInvalidName(input.profileId);
+    if (invalidName !== null) {
+        return invalidName;
+    }
+    const apiKey = input.apiKey.trim();
+    if (apiKey === "") {
+        return {
+            kind: ADD_API_KEY_PROFILE_RESULT.emptyKey,
+            profileId: input.profileId,
+        };
+    }
+    const home = openAgentsHome(input);
+    if (await findProfile(home.config, input.profileId)) {
+        return {
+            kind: ADD_API_KEY_PROFILE_RESULT.profileExists,
+            profileId: input.profileId,
+        };
+    }
+    const secret = createKeyringSecretRef(input.profileId);
+    await home.keyring.set(secret.id, apiKey);
+    try {
+        const profile = await home.config.profiles.addApiKey({
+            id: input.profileId,
+            agentId: input.agentId,
+            secret,
+        });
+        return { kind: ADD_API_KEY_PROFILE_RESULT.registered, profile };
+    }
+    catch (thrown) {
+        await home.keyring.delete(secret.id);
+        throw thrown;
+    }
+}
+/**
+ * One record per addable kind (design principle 7): the key IS the support
+ * declaration, so adding a kind is adding a row rather than a branch.
+ */
+const AGENT_CONFIG_BUILDER = {
+    [AGENT_ADD_KIND.openaiCompatible]: (request) => openAiCompatibleAgentConfig({
+        id: request.id,
+        baseUrl: request.baseUrl,
+        model: request.model,
+        ...(request.apiKeyEnv === undefined
+            ? {}
+            : { apiKey: envTemplate(request.apiKeyEnv) }),
+        ...(request.engine === undefined ? {} : { engine: request.engine }),
+    }),
+};
+/** Add an agent of the requested kind. `input.kind` is the discriminator. */
+export async function addAgentConfig(input) {
+    const invalidName = rejectInvalidName(input.id);
+    if (invalidName !== null) {
+        return invalidName;
+    }
+    const home = openAgentsHome(input);
+    const existing = await home.config.agentConfigs.list();
+    if (existing.some((agentConfig) => agentConfig.id === input.id)) {
+        return { kind: ADD_AGENT_CONFIG_RESULT.exists, id: input.id };
+    }
+    const agentConfig = await home.config.agentConfigs.add(AGENT_CONFIG_BUILDER[input.kind](input));
+    return { kind: ADD_AGENT_CONFIG_RESULT.added, agentConfig };
+}
+function envTemplate(name) {
+    return `\${${name}}`;
+}
+async function findProfile(config, profileId) {
+    return (await config.profiles.list()).some((profile) => profile.id === profileId);
+}
+/**
+ * Events are informational; a consumer that does not want them must not stall
+ * the sign-in, and a consumer that does must see them all before the result is
+ * reported. Awaiting the drain after the result gives both.
+ */
+async function drainLoginEvents(events, onEvent) {
+    if (onEvent === undefined) {
+        return;
+    }
+    for await (const event of events) {
+        onEvent(event);
+    }
+}

package/dist/remove.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The one way an agent leaves the shared home. `name` is a record name, the
+ * same position `connection login <name>` uses, and profiles win over agent
+ * configs because a profile is the more specific thing an operator names.
+ */
+import type { AgentConfig, ProfileRecord } from "@alpacakit/agents/config";
+import { type AgentsHomeInput } from "./home.js";
+import { type InvalidNameResult } from "./names.js";
+export declare const REMOVE_AGENTS_HOME_ENTRY_RESULT: {
+    readonly removedProfile: "removed_profile";
+    readonly removedAgentConfig: "removed_agent_config";
+    readonly notFound: "not_found";
+};
+export type RemoveAgentsHomeEntryInput = AgentsHomeInput & {
+    readonly name: string;
+};
+export type RemoveAgentsHomeEntryResult = {
+    readonly kind: typeof REMOVE_AGENTS_HOME_ENTRY_RESULT.removedProfile;
+    readonly profile: ProfileRecord;
+    /** The login home deleted, or `null` when the path was not ours to delete. */
+    readonly removedManagedHome: string | null;
+    readonly removedSecret: boolean;
+} | {
+    readonly kind: typeof REMOVE_AGENTS_HOME_ENTRY_RESULT.removedAgentConfig;
+    readonly agentConfig: AgentConfig;
+} | {
+    readonly kind: typeof REMOVE_AGENTS_HOME_ENTRY_RESULT.notFound;
+    readonly name: string;
+} | InvalidNameResult;
+/**
+ * The record goes first, then the credential it pointed at: if deleting the
+ * credential fails the operator is left with an inert directory or an orphaned
+ * keychain entry and a loud error — never with a live record pointing at a
+ * credential that is already gone.
+ *
+ * Only artifacts this package created are deleted. A home the operator pointed
+ * at themselves, or a secret behind someone else's resolver, is theirs.
+ */
+export declare function removeAgentsHomeEntry(input: RemoveAgentsHomeEntryInput): Promise<RemoveAgentsHomeEntryResult>;
+//# sourceMappingURL=remove.d.ts.map