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

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -0,0 +1,388 @@
+/**
+ * `@alpacakit/agents-conventions/cli` — the `agent` command surface, as DATA.
+ *
+ * There is no `bin` or CLI runtime here: this module owns the vocabulary (the
+ * command path, flags, procedure input projection, shared procedure bridge,
+ * and result schema) so that `alpacaloop agent login`, `promptopt agent login`
+ * and `semantic-trigger agent login` are the same command. Each product mounts
+ * `AGENT_CLI_SURFACE.node`, supplies an invocation context after parsing, and
+ * owns presentation of the typed outcome.
+ *
+ * `@alpacakit/channels` and `zod` are peers: importing the procedures must not
+ * drag a CLI framework in.
+ */
+import { BUILTIN_AGENT_ID, LOGIN_METHOD, } from "@alpacakit/agents";
+import { OPENAI_COMPATIBLE_ENGINE } from "@alpacakit/agents/config";
+import { codecs, createOutputContract, defineEntry, defineEntryEndpoint, defineEntryNode, defineParameter, optional, required, VALUE_SHAPE_KIND, } from "@alpacakit/channels";
+import { bindCliEntry, CLI_BOOLEAN_MODE, overrideCliSegment, } from "@alpacakit/channels/cli";
+import { z } from "zod";
+import { agentAddOutputSchema, agentCredentialAddOutputSchema, agentListOutputSchema, agentLoginOutputSchema, agentRemoveOutputSchema, } from "./cli-output.js";
+import { listAgentsHome, } from "./home.js";
+import { AGENTS_HOME_RECORD_NAME_PATTERN, AGENTS_HOME_RECORD_NAME_RULE, } from "./names.js";
+import { addAgentConfig, addApiKeyProfile, loginManagedHome, } from "./register.js";
+import { removeAgentsHomeEntry, } from "./remove.js";
+import { AGENT_ADD_KIND } from "./values.js";
+export const AGENT_ENTRY_NAME = {
+    list: "agent-list",
+    login: "agent-login",
+    credentialAdd: "agent-credential-add",
+    add: "agent-add",
+    remove: "agent-remove",
+};
+const AGENT_CLI_TOKEN = {
+    agent: "agent",
+    list: "list",
+    login: "login",
+    credential: "credential",
+    add: "add",
+    remove: "remove",
+};
+const LOGIN_AGENT_IDS = [
+    BUILTIN_AGENT_ID.claude,
+    BUILTIN_AGENT_ID.codex,
+];
+const LOGIN_METHODS = [LOGIN_METHOD.oauth, LOGIN_METHOD.device];
+const ENGINES = [
+    OPENAI_COMPATIBLE_ENGINE.fetch,
+    OPENAI_COMPATIBLE_ENGINE.pi,
+];
+const ADD_KINDS = [AGENT_ADD_KIND.openaiCompatible];
+const AGENT_CLI_DESCRIPTION = {
+    agent: "Shared agents home: list, sign in, add, and remove agents.",
+    credential: "Agent credentials.",
+    list: "List registered agents and their execution readiness.",
+    login: "Sign in to an agent and register the credential as a profile.",
+    credentialAdd: "Store an API key for an agent and register it as a profile.",
+    add: "Add an agent that speaks an OpenAI-compatible endpoint.",
+    remove: "Remove a profile or an added agent by name.",
+};
+const AGENT_CLI_PARAMETER_DESCRIPTION = {
+    profileId: "Profile name to create.",
+    loginAgentId: `Agent to sign in: ${LOGIN_AGENT_IDS.join(", ")}.`,
+    credentialAgentId: "Agent the key authenticates; a built-in id or an added agent id.",
+    method: `Sign-in method: ${LOGIN_METHODS.join(", ")}. Defaults to ${LOGIN_METHOD.oauth}.`,
+    stdin: "Read the API key from standard input.",
+    addId: "Agent name to create; also the agent id runs refer to.",
+    addKind: `Agent kind: ${ADD_KINDS.join(", ")}.`,
+    baseUrl: "OpenAI-compatible endpoint base URL.",
+    model: "Model the agent requests.",
+    apiKeyEnv: "Environment variable holding the API key; stored as a template, never the key itself.",
+    engine: `Execution engine: ${ENGINES.join(", ")}. Defaults to ${OPENAI_COMPATIBLE_ENGINE.fetch}.`,
+    removeName: "Profile name, or the name of an added agent.",
+};
+/**
+ * Record names reach the filesystem and the keychain, so the surface refuses
+ * anything outside the family grammar here rather than letting a handler
+ * discover it. The procedures repeat the check for callers that skip the CLI.
+ */
+function recordNameCodec() {
+    return codecs.define({
+        schema: z
+            .string()
+            .regex(AGENTS_HOME_RECORD_NAME_PATTERN, AGENTS_HOME_RECORD_NAME_RULE),
+        shape: { kind: VALUE_SHAPE_KIND.string },
+    });
+}
+/** `--stdin` is a source selection flag, so only its selected state is input. */
+function stdinSelectionCodec() {
+    return codecs.define({
+        schema: z.literal(true),
+        shape: { kind: VALUE_SHAPE_KIND.boolean },
+    });
+}
+const AGENT_CLI_HELP = {
+    agent: {
+        examples: [
+            {
+                title: "Inspect the shared agents home",
+                useWhen: "checking which agents this machine can run",
+                command: "agent list",
+            },
+        ],
+    },
+};
+const listEntry = defineEntry({
+    name: AGENT_ENTRY_NAME.list,
+    parameters: [],
+    project: () => ({}),
+    output: createOutputContract(agentListOutputSchema),
+});
+const loginEntry = defineEntry({
+    name: AGENT_ENTRY_NAME.login,
+    parameters: [
+        defineParameter({
+            name: "profileId",
+            codec: recordNameCodec(),
+            requirement: required(),
+            description: AGENT_CLI_PARAMETER_DESCRIPTION.profileId,
+        }),
+        defineParameter({
+            name: "agentId",
+            codec: codecs.stringEnum(LOGIN_AGENT_IDS),
+            requirement: required(),
+            description: AGENT_CLI_PARAMETER_DESCRIPTION.loginAgentId,
+        }),
+        defineParameter({
+            name: "method",
+            codec: codecs.stringEnum(LOGIN_METHODS),
+            requirement: optional({ default: LOGIN_METHOD.oauth }),
+            description: AGENT_CLI_PARAMETER_DESCRIPTION.method,
+        }),
+    ],
+    project: ({ values }) => values,
+    output: createOutputContract(agentLoginOutputSchema),
+});
+const credentialAddEntry = defineEntry({
+    name: AGENT_ENTRY_NAME.credentialAdd,
+    parameters: [
+        defineParameter({
+            name: "profileId",
+            codec: recordNameCodec(),
+            requirement: required(),
+            description: AGENT_CLI_PARAMETER_DESCRIPTION.profileId,
+        }),
+        // Not an enum: `agent add` mints ids this command must be able to name.
+        defineParameter({
+            name: "agentId",
+            codec: codecs.string(),
+            requirement: required(),
+            description: AGENT_CLI_PARAMETER_DESCRIPTION.credentialAgentId,
+        }),
+        defineParameter({
+            // Required, not defaulted: stdin is the ONLY way in for the key, so
+            // `false` could never be a request this command can serve.
+            name: "stdin",
+            codec: stdinSelectionCodec(),
+            requirement: required(),
+            description: AGENT_CLI_PARAMETER_DESCRIPTION.stdin,
+        }),
+    ],
+    project: ({ values }) => values,
+    output: createOutputContract(agentCredentialAddOutputSchema),
+});
+const addEntry = defineEntry({
+    name: AGENT_ENTRY_NAME.add,
+    parameters: [
+        defineParameter({
+            name: "id",
+            codec: recordNameCodec(),
+            requirement: required(),
+            description: AGENT_CLI_PARAMETER_DESCRIPTION.addId,
+        }),
+        defineParameter({
+            name: "kind",
+            codec: codecs.stringEnum(ADD_KINDS),
+            requirement: required(),
+            description: AGENT_CLI_PARAMETER_DESCRIPTION.addKind,
+        }),
+        defineParameter({
+            name: "baseUrl",
+            codec: codecs.string(),
+            requirement: required(),
+            description: AGENT_CLI_PARAMETER_DESCRIPTION.baseUrl,
+        }),
+        defineParameter({
+            name: "model",
+            codec: codecs.string(),
+            requirement: required(),
+            description: AGENT_CLI_PARAMETER_DESCRIPTION.model,
+        }),
+        defineParameter({
+            name: "apiKeyEnv",
+            codec: codecs.string(),
+            requirement: optional(),
+            description: AGENT_CLI_PARAMETER_DESCRIPTION.apiKeyEnv,
+        }),
+        defineParameter({
+            // Optional with NO default: omitting `--engine` must reach
+            // `addAgentConfig` as an absent field, so the agent-config payload
+            // stays the one place that decides what "unset" means.
+            name: "engine",
+            codec: codecs.stringEnum(ENGINES),
+            requirement: optional(),
+            description: AGENT_CLI_PARAMETER_DESCRIPTION.engine,
+        }),
+    ],
+    project: ({ values }) => values,
+    output: createOutputContract(agentAddOutputSchema),
+});
+const removeEntry = defineEntry({
+    name: AGENT_ENTRY_NAME.remove,
+    parameters: [
+        defineParameter({
+            name: "name",
+            codec: recordNameCodec(),
+            requirement: required(),
+            description: AGENT_CLI_PARAMETER_DESCRIPTION.removeName,
+        }),
+    ],
+    project: ({ values }) => values,
+    output: createOutputContract(agentRemoveOutputSchema),
+});
+export async function executeAgentList(_input, context) {
+    const result = await listAgentsHome(context);
+    return { operation: AGENT_ENTRY_NAME.list, result };
+}
+export async function executeAgentLogin(input, context) {
+    const result = await loginManagedHome({
+        ...context,
+        ...input,
+        onEvent: context.onLoginEvent,
+    });
+    return { operation: AGENT_ENTRY_NAME.login, result };
+}
+export async function executeAgentCredentialAdd(input, context) {
+    const apiKey = await context.readCredentialSecret();
+    const result = await addApiKeyProfile({
+        ...context,
+        profileId: input.profileId,
+        agentId: input.agentId,
+        apiKey,
+    });
+    return { operation: AGENT_ENTRY_NAME.credentialAdd, result };
+}
+export async function executeAgentAdd(input, context) {
+    const result = await addAgentConfig({
+        ...context,
+        ...input,
+    });
+    return { operation: AGENT_ENTRY_NAME.add, result };
+}
+export async function executeAgentRemove(input, context) {
+    const result = await removeAgentsHomeEntry({
+        ...context,
+        ...input,
+    });
+    return { operation: AGENT_ENTRY_NAME.remove, result };
+}
+const listEndpoint = defineEntryEndpoint(listEntry, {
+    handler: executeAgentList,
+    channels: [bindCliEntry({ parameters: [] })],
+});
+const loginEndpoint = defineEntryEndpoint(loginEntry, {
+    handler: executeAgentLogin,
+    channels: [
+        bindCliEntry({
+            parameters: [
+                {
+                    kind: "positional",
+                    parameterName: "profileId",
+                    valueName: "PROFILE",
+                },
+                { kind: "option", parameterName: "agentId", flags: ["--agent"] },
+                { kind: "option", parameterName: "method", flags: ["--method"] },
+            ],
+        }),
+    ],
+});
+const credentialAddEndpoint = defineEntryEndpoint(credentialAddEntry, {
+    handler: executeAgentCredentialAdd,
+    channels: [
+        bindCliEntry({
+            parameters: [
+                {
+                    kind: "positional",
+                    parameterName: "profileId",
+                    valueName: "PROFILE",
+                },
+                { kind: "option", parameterName: "agentId", flags: ["--agent"] },
+                {
+                    kind: "option",
+                    parameterName: "stdin",
+                    flags: ["--stdin"],
+                    // A required boolean would otherwise take a value (`--stdin true`).
+                    booleanMode: CLI_BOOLEAN_MODE.flag,
+                },
+            ],
+        }),
+    ],
+});
+const addEndpoint = defineEntryEndpoint(addEntry, {
+    handler: executeAgentAdd,
+    channels: [
+        bindCliEntry({
+            parameters: [
+                { kind: "positional", parameterName: "id", valueName: "ID" },
+                { kind: "option", parameterName: "kind", flags: ["--kind"] },
+                { kind: "option", parameterName: "baseUrl", flags: ["--base-url"] },
+                { kind: "option", parameterName: "model", flags: ["--model"] },
+                {
+                    kind: "option",
+                    parameterName: "apiKeyEnv",
+                    flags: ["--api-key-env"],
+                },
+                { kind: "option", parameterName: "engine", flags: ["--engine"] },
+            ],
+        }),
+    ],
+});
+const removeEndpoint = defineEntryEndpoint(removeEntry, {
+    handler: executeAgentRemove,
+    channels: [
+        bindCliEntry({
+            parameters: [
+                { kind: "positional", parameterName: "name", valueName: "NAME" },
+            ],
+        }),
+    ],
+});
+const agentNode = defineEntryNode({
+    name: AGENT_CLI_TOKEN.agent,
+    description: AGENT_CLI_DESCRIPTION.agent,
+    segments: [
+        overrideCliSegment({
+            token: AGENT_CLI_TOKEN.agent,
+            help: AGENT_CLI_HELP.agent,
+        }),
+    ],
+    children: [
+        defineEntryNode({
+            name: AGENT_CLI_TOKEN.list,
+            description: AGENT_CLI_DESCRIPTION.list,
+            endpoints: [listEndpoint],
+        }),
+        defineEntryNode({
+            name: AGENT_CLI_TOKEN.login,
+            description: AGENT_CLI_DESCRIPTION.login,
+            endpoints: [loginEndpoint],
+        }),
+        defineEntryNode({
+            name: AGENT_CLI_TOKEN.credential,
+            description: AGENT_CLI_DESCRIPTION.credential,
+            children: [
+                defineEntryNode({
+                    name: AGENT_CLI_TOKEN.add,
+                    description: AGENT_CLI_DESCRIPTION.credentialAdd,
+                    endpoints: [credentialAddEndpoint],
+                }),
+            ],
+        }),
+        defineEntryNode({
+            name: AGENT_CLI_TOKEN.add,
+            description: AGENT_CLI_DESCRIPTION.add,
+            endpoints: [addEndpoint],
+        }),
+        defineEntryNode({
+            name: AGENT_CLI_TOKEN.remove,
+            description: AGENT_CLI_DESCRIPTION.remove,
+            endpoints: [removeEndpoint],
+        }),
+    ],
+});
+export const AGENT_CLI_SURFACE = {
+    node: agentNode,
+    endpoints: {
+        list: listEndpoint,
+        login: loginEndpoint,
+        credentialAdd: credentialAddEndpoint,
+        add: addEndpoint,
+        remove: removeEndpoint,
+    },
+    outputs: {
+        list: listEntry.output,
+        login: loginEntry.output,
+        credentialAdd: credentialAddEntry.output,
+        add: addEntry.output,
+        remove: removeEntry.output,
+    },
+};

package/dist/home.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The shared seam every family procedure opens: one `~/.alpaca/agents` home,
+ * one runtime bound to the caller's environment, and one keychain store.
+ * Nothing here reaches for ambient state — `homeDir`, `env`, ports and the
+ * keyring are all inbound, so a test drives the whole procedure against a
+ * temp directory and fakes.
+ */
+import { type AgentAvailability, type AgentRuntime, type HostLocation, type Ports } from "@alpacakit/agents";
+import { type AgentsConfig, type AgentsRuntimeConfig, type CandidateSource } from "@alpacakit/agents/config";
+import { type KeyringSecretStore } from "@alpacakit/core/keyring";
+import { type AgentsConfigOptionsInput } from "./paths.js";
+/**
+ * What every procedure takes. `ports` and `keyring` exist so tests can drive
+ * the real code path without a subprocess or a real keychain; both default to
+ * the production implementations.
+ */
+export type AgentsHomeInput = AgentsConfigOptionsInput & {
+    readonly ports?: Partial<Ports>;
+    readonly keyring?: KeyringSecretStore;
+};
+export type AgentsHomeEntry = {
+    readonly agentId: string;
+    readonly agentConfigId: string;
+    /** The agent config kind the entry comes from (`codex`, `openai-compatible`, …). */
+    readonly kind: string;
+    readonly source: CandidateSource;
+    readonly profileId: string | null;
+    /** `null` when the agent declares no availability probe (I3 `agent add` kinds). */
+    readonly availability: AgentAvailability | null;
+};
+export type AgentsHomeListing = {
+    readonly agentsHome: string;
+    readonly entries: readonly AgentsHomeEntry[];
+};
+export type OpenedAgentsHome = {
+    readonly agentsHome: string;
+    readonly config: AgentsConfig;
+    readonly location: HostLocation;
+    readonly keyring: KeyringSecretStore;
+    readonly ports: Partial<Ports>;
+    readonly baseEnv: Record<string, string>;
+};
+export declare function openAgentsHome(input: AgentsHomeInput): OpenedAgentsHome;
+/**
+ * Every agent this machine can currently reach, in the home's own order, with
+ * the readiness each one actually has: a profile-backed candidate is probed
+ * with that profile's environment applied, exactly as `createFleet` applies it
+ * before a run — otherwise `agent list` would report the ambient login for a
+ * profile that has its own.
+ */
+export declare function listAgentsHome(input: AgentsHomeInput): Promise<AgentsHomeListing>;
+export type RuntimeFactory = {
+    /** The runtime bound to the caller's own environment. */
+    readonly ambient: AgentRuntime;
+    /** A runtime bound to the caller's environment plus one profile's patch. */
+    withEnvPatch(baseEnv: Record<string, string>): AgentRuntime;
+    readonly baseEnv: Record<string, string>;
+};
+/**
+ * Builds runtimes over the home's agents. The config's own secret resolvers
+ * are merged into `ports.secrets`, so an api-key profile resolves through the
+ * family keyring resolver rather than failing as an unknown resolver name.
+ */
+export declare function createRuntimeFactory(home: OpenedAgentsHome, config: AgentsRuntimeConfig): RuntimeFactory;
+//# sourceMappingURL=home.d.ts.map

package/dist/home.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"home.d.ts","sourceRoot":"","sources":["../src/home.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAIjB,KAAK,YAAY,EACjB,KAAK,KAAK,EAEX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EAGrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,KAAK,wBAAwB,EAG9B,MAAM,YAAY,CAAC;AAGpB;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,wBAAwB,GAAG;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mFAAmF;IACnF,QAAQ,CAAC,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACjD,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;CAC9C,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C,CAAC;AAOF,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CAUvE;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,iBAAiB,CAAC,CAgB5B;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,4EAA4E;IAC5E,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,YAAY,CAAC;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,mBAAmB,GAC1B,cAAc,CAahB"}

package/dist/home.js

@@ -0,0 +1,105 @@
+/**
+ * The shared seam every family procedure opens: one `~/.alpaca/agents` home,
+ * one runtime bound to the caller's environment, and one keychain store.
+ * Nothing here reaches for ambient state — `homeDir`, `env`, ports and the
+ * keyring are all inbound, so a test drives the whole procedure against a
+ * temp directory and fakes.
+ */
+import { AGENT_AVAILABILITY_STATUS, AGENT_INDETERMINATE_REASON, applyEnvPatch, createAgentRuntime, resolvePorts, } from "@alpacakit/agents";
+import { openAgentsConfig, secretsForRuntime, } from "@alpacakit/agents/config";
+import { keyringSecretStore, } from "@alpacakit/core/keyring";
+import { resolveAgentsConfigOptions, resolveAgentsHome, } from "./paths.js";
+import { AGENTS_KEYRING_SERVICE } from "./values.js";
+const AVAILABILITY_DETAIL = {
+    profileEnvUnresolved: "Profile credentials could not be resolved, so availability was not probed.",
+};
+export function openAgentsHome(input) {
+    return {
+        agentsHome: resolveAgentsHome(input),
+        config: openAgentsConfig(resolveAgentsConfigOptions(input)),
+        location: { homeDir: input.homeDir },
+        keyring: input.keyring ?? keyringSecretStore({ service: AGENTS_KEYRING_SERVICE }),
+        ports: input.ports ?? {},
+        baseEnv: definedEnv(input.env),
+    };
+}
+/**
+ * Every agent this machine can currently reach, in the home's own order, with
+ * the readiness each one actually has: a profile-backed candidate is probed
+ * with that profile's environment applied, exactly as `createFleet` applies it
+ * before a run — otherwise `agent list` would report the ambient login for a
+ * profile that has its own.
+ */
+export async function listAgentsHome(input) {
+    const home = openAgentsHome(input);
+    const config = await home.config.loadRuntimeConfig();
+    const runtimes = createRuntimeFactory(home, config);
+    const entries = [];
+    for (const { candidate, source } of config.candidates) {
+        entries.push({
+            agentId: candidate.agentId,
+            agentConfigId: source.agentConfigId,
+            kind: source.agentConfigKind,
+            source: source.kind,
+            profileId: source.profileId,
+            availability: await probeCandidate(runtimes, home.location, candidate),
+        });
+    }
+    return { agentsHome: home.agentsHome, entries };
+}
+/**
+ * Builds runtimes over the home's agents. The config's own secret resolvers
+ * are merged into `ports.secrets`, so an api-key profile resolves through the
+ * family keyring resolver rather than failing as an unknown resolver name.
+ */
+export function createRuntimeFactory(home, config) {
+    const resolved = resolvePorts(home.ports);
+    const ports = {
+        ...resolved,
+        secrets: { ...resolved.secrets, ...secretsForRuntime(config) },
+    };
+    const withEnvPatch = (baseEnv) => createAgentRuntime({ agents: config.agents, baseEnv, ports });
+    return {
+        ambient: withEnvPatch(home.baseEnv),
+        withEnvPatch,
+        baseEnv: home.baseEnv,
+    };
+}
+async function probeCandidate(runtimes, location, candidate) {
+    const agent = runtimes.ambient.agent(candidate.agentId);
+    if (agent.availability === null) {
+        return null;
+    }
+    const { profile } = candidate;
+    if (profile === undefined) {
+        return await agent.availability.probe(location);
+    }
+    if (agent.auth === null) {
+        return null;
+    }
+    let scoped;
+    try {
+        scoped = runtimes.withEnvPatch(applyEnvPatch(runtimes.baseEnv, await agent.auth.toEnv(profile.material)));
+    }
+    catch {
+        // A credential we cannot read is not an answer about the agent: report
+        // that the probe could not run rather than failing the whole listing or
+        // silently reporting the ambient login instead of the profile's.
+        return {
+            status: AGENT_AVAILABILITY_STATUS.indeterminate,
+            reason: AGENT_INDETERMINATE_REASON.probeFault,
+            detail: AVAILABILITY_DETAIL.profileEnvUnresolved,
+        };
+    }
+    return ((await scoped.agent(candidate.agentId).availability?.probe(location)) ??
+        null);
+}
+function definedEnv(env) {
+    const defined = {};
+    for (const [name, value] of Object.entries(env)) {
+        if (value !== undefined) {
+            defined[name] = value;
+        }
+    }
+    return defined;
+}

package/dist/index.d.ts

@@ -1,29 +1,27 @@
 /**
- * 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 type { SecretRef } from "@alpacakit/agents";
-import type { OpenAgentsConfigOptions } from "@alpacakit/agents/config";
-export declare const ALPACA_LOOP_AGENTS_CONFIG_ENV_VAR = "ALPACA_AGENTS_HOME";
-export declare const ALPACA_LOOP_AGENTS_CONFIG_DIRECTORY = ".alpaca/agents";
-export declare const ALPACA_LOOP_AGENTS_CONFIG_KEYRING_SERVICE = "alpacaloop.agents-home";
-export declare const ALPACA_LOOP_AGENTS_CONFIG_KEYRING_RESOLVER = "agents-home-keyring";
-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;
-export declare function createKeyringSecretRef(profileId: string): SecretRef;
-export declare function resolveManagedHomePath(input: ManagedHomePathInput): string;
+export type { AgentsHomeEntry, AgentsHomeInput, AgentsHomeListing, OpenedAgentsHome, RuntimeFactory, } from "./home.js";
+export { createRuntimeFactory, listAgentsHome, openAgentsHome, } from "./home.js";
+export type { InvalidNameResult } from "./names.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 type { AgentsConfigOptionsInput, ManagedHomePathInput, } from "./paths.js";
+export { createKeyringSecretRef, isManagedHomePath, resolveAgentsConfigOptions, resolveAgentsHome, resolveManagedHomePath, } from "./paths.js";
+export type { AddAgentConfigInput, AddAgentConfigResult, AddApiKeyProfileInput, AddApiKeyProfileResult, AgentConfigRequest, LoginManagedHomeInput, LoginManagedHomeResult, OpenAiCompatibleAgentConfigRequest, } from "./register.js";
+export { ADD_AGENT_CONFIG_RESULT, ADD_API_KEY_PROFILE_RESULT, addAgentConfig, addApiKeyProfile, LOGIN_MANAGED_HOME_RESULT, loginManagedHome, } from "./register.js";
+export type { RemoveAgentsHomeEntryInput, RemoveAgentsHomeEntryResult, } from "./remove.js";
+export { REMOVE_AGENTS_HOME_ENTRY_RESULT, removeAgentsHomeEntry, } from "./remove.js";
+export type { AgentAddKind } from "./values.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";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAEV,uBAAuB,EACxB,MAAM,0BAA0B,CAAC;AAGlC,eAAO,MAAM,iCAAiC,uBAAuB,CAAC;AACtE,eAAO,MAAM,mCAAmC,mBAAmB,CAAC;AACpE,eAAO,MAAM,yCAAyC,2BAC5B,CAAC;AAC3B,eAAO,MAAM,0CAA0C,wBAAwB,CAAC;AAQhF,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,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CASnE;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAM1E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,YAAY,EACV,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EACL,kCAAkC,EAClC,+BAA+B,EAC/B,4BAA4B,EAC5B,wBAAwB,EACxB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,0BAA0B,EAC1B,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,kCAAkC,GACnC,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,cAAc,EACd,gBAAgB,EAChB,yBAAyB,EACzB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,+BAA+B,EAC/B,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,8BAA8B,GAC/B,MAAM,aAAa,CAAC"}