@alpacakit/agents-conventions 0.1.0-beta.35 → 0.1.0-beta.37

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

package/dist/remove.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove.d.ts","sourceRoot":"","sources":["../src/remove.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE3E,OAAO,EAAE,KAAK,eAAe,EAAkB,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,KAAK,iBAAiB,EAAqB,MAAM,YAAY,CAAC;AAGvE,eAAO,MAAM,+BAA+B;;;;CAIlC,CAAC;AAEX,MAAM,MAAM,0BAA0B,GAAG,eAAe,GAAG;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,2BAA2B,GACnC;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,+BAA+B,CAAC,cAAc,CAAC;IACrE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,+BAA+B,CAAC,kBAAkB,CAAC;IACzE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,+BAA+B,CAAC,QAAQ,CAAC;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,GACD,iBAAiB,CAAC;AAEtB;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,2BAA2B,CAAC,CAyBtC"}

package/dist/remove.js

@@ -0,0 +1,73 @@
+/**
+ * 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 { rm } from "node:fs/promises";
+import { AUTH_MATERIAL_KIND } from "@alpacakit/agents";
+import { openAgentsHome } from "./home.js";
+import { rejectInvalidName } from "./names.js";
+import { createKeyringSecretRef, isManagedHomePath } from "./paths.js";
+export const REMOVE_AGENTS_HOME_ENTRY_RESULT = {
+    removedProfile: "removed_profile",
+    removedAgentConfig: "removed_agent_config",
+    notFound: "not_found",
+};
+/**
+ * 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 async function removeAgentsHomeEntry(input) {
+    // Nothing this package created can carry a name outside the grammar, so a
+    // name outside it cannot match a record — and must never reach the delete.
+    const invalidName = rejectInvalidName(input.name);
+    if (invalidName !== null) {
+        return invalidName;
+    }
+    const home = openAgentsHome(input);
+    const profile = await home.config.profiles.remove(input.name);
+    if (profile !== null) {
+        return {
+            kind: REMOVE_AGENTS_HOME_ENTRY_RESULT.removedProfile,
+            profile,
+            removedManagedHome: await removeManagedHome(home.agentsHome, profile),
+            removedSecret: await removeManagedSecret(home.keyring, profile),
+        };
+    }
+    const agentConfig = await home.config.agentConfigs.remove(input.name);
+    if (agentConfig !== null) {
+        return {
+            kind: REMOVE_AGENTS_HOME_ENTRY_RESULT.removedAgentConfig,
+            agentConfig,
+        };
+    }
+    return { kind: REMOVE_AGENTS_HOME_ENTRY_RESULT.notFound, name: input.name };
+}
+async function removeManagedHome(agentsHome, profile) {
+    if (profile.material.kind !== AUTH_MATERIAL_KIND.homeDir) {
+        return null;
+    }
+    const { path } = profile.material;
+    if (!isManagedHomePath({ rootDir: agentsHome, profileId: profile.id, path })) {
+        return null;
+    }
+    await rm(path, { recursive: true, force: true });
+    return path;
+}
+async function removeManagedSecret(keyring, profile) {
+    if (profile.material.kind !== AUTH_MATERIAL_KIND.apiKey) {
+        return false;
+    }
+    const managed = createKeyringSecretRef(profile.id);
+    const { secret } = profile.material;
+    if (secret.resolver !== managed.resolver || secret.id !== managed.id) {
+        return false;
+    }
+    await keyring.delete(secret.id);
+    return true;
+}

package/dist/values.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The family vocabulary, spelled once. Every constant here is a decision
+ * about WHERE shared agent state lives on a machine — the one thing every
+ * AlpacaKit-family product must agree on to see the same agents.
+ */
+export declare const AGENTS_HOME_ENV_VAR = "ALPACA_AGENTS_HOME";
+export declare const AGENTS_HOME_DIRECTORY = ".alpaca/agents";
+/** Keychain service for agent credentials — distinct from integrations (I1). */
+export declare const AGENTS_KEYRING_SERVICE = "alpaca.agents";
+export declare const AGENTS_KEYRING_RESOLVER = "agents-home-keyring";
+/** Login homes this package creates, and is therefore allowed to delete. */
+export declare const AGENTS_MANAGED_HOMES_DIRECTORY = "managed-homes";
+export declare const AGENTS_KEYRING_ACCOUNT: {
+    readonly prefix: "profile";
+    readonly apiKeySuffix: "api-key";
+    readonly separator: ":";
+};
+/**
+ * Which agent kinds an operator can add to the shared home. Deciding this is
+ * the family's job, not a product's, so the vocabulary lives beside the
+ * procedure that acts on it — `./cli` only spells it as a flag.
+ *
+ * A literal, because `AGENT_CONFIG_KIND` values are branded and cannot be a
+ * CLI enum; a test pins the two together so they cannot drift.
+ */
+export declare const AGENT_ADD_KIND: {
+    readonly openaiCompatible: "openai-compatible";
+};
+export type AgentAddKind = (typeof AGENT_ADD_KIND)[keyof typeof AGENT_ADD_KIND];
+//# sourceMappingURL=values.d.ts.map

package/dist/values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../src/values.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,mBAAmB,uBAAuB,CAAC;AACxD,eAAO,MAAM,qBAAqB,mBAAmB,CAAC;AACtD,gFAAgF;AAChF,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AACtD,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAC7D,4EAA4E;AAC5E,eAAO,MAAM,8BAA8B,kBAAkB,CAAC;AAC9D,eAAO,MAAM,sBAAsB;;;;CAIzB,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;CAEjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC"}

package/dist/values.js

@@ -0,0 +1,28 @@
+/**
+ * The family vocabulary, spelled once. Every constant here is a decision
+ * about WHERE shared agent state lives on a machine — the one thing every
+ * AlpacaKit-family product must agree on to see the same agents.
+ */
+export const AGENTS_HOME_ENV_VAR = "ALPACA_AGENTS_HOME";
+export const AGENTS_HOME_DIRECTORY = ".alpaca/agents";
+/** Keychain service for agent credentials — distinct from integrations (I1). */
+export const AGENTS_KEYRING_SERVICE = "alpaca.agents";
+export const AGENTS_KEYRING_RESOLVER = "agents-home-keyring";
+/** Login homes this package creates, and is therefore allowed to delete. */
+export const AGENTS_MANAGED_HOMES_DIRECTORY = "managed-homes";
+export const AGENTS_KEYRING_ACCOUNT = {
+    prefix: "profile",
+    apiKeySuffix: "api-key",
+    separator: ":",
+};
+/**
+ * Which agent kinds an operator can add to the shared home. Deciding this is
+ * the family's job, not a product's, so the vocabulary lives beside the
+ * procedure that acts on it — `./cli` only spells it as a flag.
+ *
+ * A literal, because `AGENT_CONFIG_KIND` values are branded and cannot be a
+ * CLI enum; a test pins the two together so they cannot drift.
+ */
+export const AGENT_ADD_KIND = {
+    openaiCompatible: "openai-compatible",
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alpacakit/agents-conventions",
-  "version": "0.1.0-beta.35",
-  "description": "AlpacaKit-family conventions for @alpacakit/agents machine-local config (paths, keyring, managed homes).",
+  "version": "0.1.0-beta.37",
+  "description": "AlpacaKit-family conventions for @alpacakit/agents machine-local config (paths, keyring, managed homes) and the shared `agent` command surface.",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
@@ -12,6 +12,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
     }
   },
   "types": "./dist/index.d.ts",
@@ -21,11 +25,18 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@alpacakit/agents": "0.1.0-beta.35"
+    "@alpacakit/core": "0.1.0-beta.37",
+    "@alpacakit/agents": "0.1.0-beta.37"
   },
   "devDependencies": {
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.0.18",
+    "zod": "4.3.6",
+    "@alpacakit/channels": "0.1.0-beta.37"
+  },
+  "peerDependencies": {
+    "zod": "^4.3.6",
+    "@alpacakit/channels": "^0.1.0-beta.37"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",