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

package/dist/cli.d.ts

@@ -0,0 +1,186 @@
+/**
+ * `@alpacakit/agents-conventions/cli` — the `agent` command surface, as DATA.
+ *
+ * There is no `bin` here and no handler: this module owns the vocabulary (the
+ * command path, the flags, the projection into a procedure input, and the JSON
+ * a result must be) so that `alpacaloop agent login`, `promptopt agent login`
+ * and `semantic-trigger agent login` are the same command. Each product mounts
+ * `AGENT_CLI_SURFACE.node` in its own tree and binds handlers that call the
+ * procedures from the root export and print the result.
+ *
+ * `@alpacakit/channels` and `zod` are peers: importing the procedures must not
+ * drag a CLI framework in.
+ */
+import { type EntryTreeNode, type OutputContract } from "@alpacakit/channels";
+import type { AgentAddOutput, AgentCredentialAddOutput, AgentListOutput, AgentLoginOutput, AgentRemoveOutput } from "./cli-output.js";
+export declare const AGENT_ENTRY_NAME: {
+    readonly list: "agent-list";
+    readonly login: "agent-login";
+    readonly credentialAdd: "agent-credential-add";
+    readonly add: "agent-add";
+    readonly remove: "agent-remove";
+};
+declare const listEndpoint: import("@alpacakit/channels").EntryTreeEndpoint<import("@alpacakit/channels").EntryDefinitionWithOutput<"agent-list", readonly [], {}, {
+    agentsHome: string;
+    entries: {
+        agentId: string;
+        agentConfigId: string;
+        kind: string;
+        source: "profile" | "ambient" | "configured";
+        profileId: string | null;
+        availability: {
+            status: "runnable";
+        } | {
+            status: "unavailable";
+            reason: "command_missing" | "authentication_required";
+            remediation: {
+                detail: string;
+                command: {
+                    executable: string;
+                    args: string[];
+                } | null;
+            } | null;
+        } | {
+            status: "indeterminate";
+            reason: "probe_timeout" | "probe_fault";
+            detail: string;
+        } | null;
+    }[];
+}>>;
+declare const loginEndpoint: import("@alpacakit/channels").EntryTreeEndpoint<import("@alpacakit/channels").EntryDefinitionWithOutput<"agent-login", readonly [import("@alpacakit/channels").ParameterDefinition<"profileId", string, import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"agentId", "claude" | "codex", import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"method", "oauth" | "device", import("@alpacakit/channels").OptionalWithDefaultParameterRequirement<"oauth">>], import("@alpacakit/channels").ParameterValues<readonly [import("@alpacakit/channels").ParameterDefinition<"profileId", string, import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"agentId", "claude" | "codex", import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"method", "oauth" | "device", import("@alpacakit/channels").OptionalWithDefaultParameterRequirement<"oauth">>]>, {
+    kind: "registered";
+    profile: {
+        id: string;
+        agentId: string;
+        material: {
+            kind: "home-dir";
+            path: string;
+        } | {
+            kind: "api-key";
+            secret: {
+                resolver: string;
+                id: string;
+            };
+        };
+    };
+    managedHome: string;
+} | {
+    kind: "profile_exists";
+    profileId: string;
+} | {
+    kind: "unknown_agent";
+    agentId: string;
+    known: string[];
+} | {
+    kind: "unsupported";
+    agentId: string;
+    method: string;
+    supported: string[];
+} | {
+    kind: "login_failed";
+    detail: string;
+    managedHome: string;
+} | {
+    kind: "invalid_name";
+    name: string;
+    rule: string;
+}>>;
+declare const credentialAddEndpoint: import("@alpacakit/channels").EntryTreeEndpoint<import("@alpacakit/channels").EntryDefinitionWithOutput<"agent-credential-add", readonly [import("@alpacakit/channels").ParameterDefinition<"profileId", string, import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"agentId", string, import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"stdin", boolean, import("@alpacakit/channels").RequiredParameterRequirement>], import("@alpacakit/channels").ParameterValues<readonly [import("@alpacakit/channels").ParameterDefinition<"profileId", string, import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"agentId", string, import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"stdin", boolean, import("@alpacakit/channels").RequiredParameterRequirement>]>, {
+    kind: "invalid_name";
+    name: string;
+    rule: string;
+} | {
+    kind: "registered";
+    profile: {
+        id: string;
+        agentId: string;
+        material: {
+            kind: "home-dir";
+            path: string;
+        } | {
+            kind: "api-key";
+            secret: {
+                resolver: string;
+                id: string;
+            };
+        };
+    };
+} | {
+    kind: "profile_exists";
+    profileId: string;
+} | {
+    kind: "empty_key";
+    profileId: string;
+}>>;
+declare const addEndpoint: import("@alpacakit/channels").EntryTreeEndpoint<import("@alpacakit/channels").EntryDefinitionWithOutput<"agent-add", readonly [import("@alpacakit/channels").ParameterDefinition<"id", string, import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"kind", "openai-compatible", import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"baseUrl", string, import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"model", string, import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"apiKeyEnv", string, import("@alpacakit/channels").OptionalParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"engine", "fetch" | "pi", import("@alpacakit/channels").OptionalParameterRequirement>], import("@alpacakit/channels").ParameterValues<readonly [import("@alpacakit/channels").ParameterDefinition<"id", string, import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"kind", "openai-compatible", import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"baseUrl", string, import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"model", string, import("@alpacakit/channels").RequiredParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"apiKeyEnv", string, import("@alpacakit/channels").OptionalParameterRequirement>, import("@alpacakit/channels").ParameterDefinition<"engine", "fetch" | "pi", import("@alpacakit/channels").OptionalParameterRequirement>]>, {
+    kind: "invalid_name";
+    name: string;
+    rule: string;
+} | {
+    kind: "added";
+    agentConfig: {
+        id: string;
+        kind: string;
+        enabled: boolean;
+        payload: Record<string, import("@alpacakit/agents").JsonValue>;
+    };
+} | {
+    kind: "exists";
+    id: string;
+}>>;
+declare const removeEndpoint: import("@alpacakit/channels").EntryTreeEndpoint<import("@alpacakit/channels").EntryDefinitionWithOutput<"agent-remove", readonly [import("@alpacakit/channels").ParameterDefinition<"name", string, import("@alpacakit/channels").RequiredParameterRequirement>], import("@alpacakit/channels").ParameterValues<readonly [import("@alpacakit/channels").ParameterDefinition<"name", string, import("@alpacakit/channels").RequiredParameterRequirement>]>, {
+    kind: "invalid_name";
+    name: string;
+    rule: string;
+} | {
+    kind: "removed_profile";
+    profile: {
+        id: string;
+        agentId: string;
+        material: {
+            kind: "home-dir";
+            path: string;
+        } | {
+            kind: "api-key";
+            secret: {
+                resolver: string;
+                id: string;
+            };
+        };
+    };
+    removedManagedHome: string | null;
+    removedSecret: boolean;
+} | {
+    kind: "removed_agent_config";
+    agentConfig: {
+        id: string;
+        kind: string;
+        enabled: boolean;
+        payload: Record<string, import("@alpacakit/agents").JsonValue>;
+    };
+} | {
+    kind: "not_found";
+    name: string;
+}>>;
+export type AgentCliSurface = {
+    /** Mount this in the product's own entry tree. */
+    readonly node: EntryTreeNode;
+    readonly endpoints: {
+        readonly list: typeof listEndpoint;
+        readonly login: typeof loginEndpoint;
+        readonly credentialAdd: typeof credentialAddEndpoint;
+        readonly add: typeof addEndpoint;
+        readonly remove: typeof removeEndpoint;
+    };
+    /** The JSON each result must be, for products that emit machine output. */
+    readonly outputs: {
+        readonly list: OutputContract<AgentListOutput>;
+        readonly login: OutputContract<AgentLoginOutput>;
+        readonly credentialAdd: OutputContract<AgentCredentialAddOutput>;
+        readonly add: OutputContract<AgentAddOutput>;
+        readonly remove: OutputContract<AgentRemoveOutput>;
+    };
+};
+export declare const AGENT_CLI_SURFACE: AgentCliSurface;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAOL,KAAK,aAAa,EAClB,KAAK,cAAc,EAIpB,MAAM,qBAAqB,CAAC;AAO7B,OAAO,KAAK,EACV,cAAc,EACd,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AAczB,eAAO,MAAM,gBAAgB;;;;;;CAMnB,CAAC;AAsMX,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;GAGjB,CAAC;AAEF,QAAA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GASlB,CAAC;AAEF,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;GAe1B,CAAC;AAEF,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;GAYhB,CAAC;AAEF,QAAA,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAOnB,CAAC;AA8CF,MAAM,MAAM,eAAe,GAAG;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC;QACnC,QAAQ,CAAC,KAAK,EAAE,OAAO,aAAa,CAAC;QACrC,QAAQ,CAAC,aAAa,EAAE,OAAO,qBAAqB,CAAC;QACrD,QAAQ,CAAC,GAAG,EAAE,OAAO,WAAW,CAAC;QACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,cAAc,CAAC;KACxC,CAAC;IACF,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,eAAe,CAAC,CAAC;QAC/C,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,gBAAgB,CAAC,CAAC;QACjD,QAAQ,CAAC,aAAa,EAAE,cAAc,CAAC,wBAAwB,CAAC,CAAC;QACjE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;QAC7C,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;KACpD,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAgB/B,CAAC"}

package/dist/cli.js

@@ -0,0 +1,307 @@
+/**
+ * `@alpacakit/agents-conventions/cli` — the `agent` command surface, as DATA.
+ *
+ * There is no `bin` here and no handler: this module owns the vocabulary (the
+ * command path, the flags, the projection into a procedure input, and the JSON
+ * a result must be) so that `alpacaloop agent login`, `promptopt agent login`
+ * and `semantic-trigger agent login` are the same command. Each product mounts
+ * `AGENT_CLI_SURFACE.node` in its own tree and binds handlers that call the
+ * procedures from the root export and print the result.
+ *
+ * `@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 { AGENTS_HOME_RECORD_NAME_PATTERN, AGENTS_HOME_RECORD_NAME_RULE, } from "./names.js";
+import { AGENT_ADD_KIND } from "./values.js";
+import { agentAddOutputSchema, agentCredentialAddOutputSchema, agentListOutputSchema, agentLoginOutputSchema, agentRemoveOutputSchema, } from "./cli-output.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 },
+    });
+}
+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: codecs.boolean(),
+            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),
+});
+const listEndpoint = defineEntryEndpoint(listEntry, bindCliEntry({ parameters: [] }));
+const loginEndpoint = defineEntryEndpoint(loginEntry, bindCliEntry({
+    parameters: [
+        { kind: "positional", parameterName: "profileId", valueName: "PROFILE" },
+        { kind: "option", parameterName: "agentId", flags: ["--agent"] },
+        { kind: "option", parameterName: "method", flags: ["--method"] },
+    ],
+}));
+const credentialAddEndpoint = defineEntryEndpoint(credentialAddEntry, 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, 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, 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,EACL,KAAK,iBAAiB,EAGtB,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;
+}