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

package/README.md

@@ -74,10 +74,11 @@ const result = await loginManagedHome({
 
 ## `@alpacakit/agents-conventions/cli`
 
-The `agent` command surface, as **data** — no `bin`, no handler, no I/O. It
-owns the command paths, the flags, the projection into a procedure input, and
-the JSON each result must be, so `alpacaloop agent login` and
-`promptopt agent login` are the same command.
+The shared `agent` Endpoint tree — no `bin`, parser, output writer, or startup
+I/O. It owns the command paths, flags, procedure-input projection, and five
+thin procedure handlers, so `alpacaloop agent login` and
+`promptopt agent login` execute the same operation. Collecting the tree and
+rendering help do not open the agents home, keyring, login process, or stdin.
 
 ```
 agent list
@@ -88,31 +89,43 @@ agent add <ID> --kind openai-compatible --base-url <URL> --model <M>
 agent remove <NAME>
 ```
 
-Mount the node in the product's tree and bind a handler per endpoint — call the
-procedure, render the result:
+Mount the node in the product's tree. The host parser passes only explicitly
+supplied canonical parameter names to `parseOptions`; after it succeeds, the
+host supplies an invocation-scoped `AgentEntryContext` and calls the collected
+handler directly:
 
 ```ts
-import { AGENT_CLI_SURFACE } from "@alpacakit/agents-conventions/cli";
-import { loginManagedHome } from "@alpacakit/agents-conventions";
-import { handleCliEndpoint } from "@alpacakit/channels/cli";
-
-// 1. mount: put AGENT_CLI_SURFACE.node among the product root's children.
-// 2. bind:
-handleCliEndpoint(AGENT_CLI_SURFACE.endpoints.login, async ({ projection }) =>
-  render(await loginManagedHome({ ...projection, homeDir, env })),
-);
+import {
+  AGENT_CLI_SURFACE,
+  type AgentEntryContext,
+} from "@alpacakit/agents-conventions/cli";
+import { collectCliCommands } from "@alpacakit/channels/cli";
+
+const view = collectCliCommands(AGENT_CLI_SURFACE.node);
+// During host action registration, for each collected command:
+const input = command.input.parseOptions(explicitCanonicalValues);
+const outcome = await command.handler(input, context satisfies AgentEntryContext);
+render(outcome); // text, JSON envelope, redaction, and exit status are host-owned
 ```
 
-Each endpoint's projection is the matching procedure's input verbatim, so the
-handler never re-maps fields: `endpoints.add` projects `{ kind, id, baseUrl,
-model, apiKeyEnv?, engine? }` straight into `addAgentConfig`. Optional flags
-stay absent when unset — `--engine` is defaulted once, by the agent-config
-payload that persists it, never a second time by the command surface. The addable kinds
-(`AGENT_ADD_KIND`) live on the root export, next to the procedure that acts on
-them — `/cli` only spells them as a flag.
-
-`AGENT_CLI_SURFACE.outputs` carries the same contracts for products that emit
-machine-readable output.
+`AgentEntryContext` contains `{ homeDir, env, ports?, keyring?,
+readCredentialSecret, onLoginEvent, signal? }`. `onLoginEvent` receives the
+typed `LoginEvent`; the host decides how to display it. `--stdin` identifies
+the input source: only the credential-add handler calls
+`readCredentialSecret()`, once, after input validation succeeds.
+
+Each handler returns `AgentEntryOutcome`, discriminated by the corresponding
+`AGENT_ENTRY_NAME` in `operation`, with the unchanged procedure result in
+`result`. This is not a CLI text/JSON envelope and carries no exit or
+presentation policy. Optional flags stay absent when unset — `--engine` is
+defaulted once by the persisted agent-config payload. The addable kinds
+(`AGENT_ADD_KIND`) remain on the root export beside the procedure that acts on
+them; `/cli` only spells them as a flag.
+
+`AGENT_CLI_SURFACE.outputs.<operation>.schema` remains the explicit validator
+for the inner procedure result used by existing projectors. It intentionally
+does not validate the tagged `AgentEntryOutcome` wrapper; presentation code
+selects the operation and validates `outcome.result` when required.
 
 `@alpacakit/channels` and `zod` are **peer** dependencies of this package: they
 are needed only by `/cli`, so importing the procedures never drags a CLI

package/dist/cli-output.js

@@ -8,8 +8,8 @@ import { AGENT_AVAILABILITY_STATUS, AGENT_INDETERMINATE_REASON, AGENT_UNAVAILABL
 import { CANDIDATE_SOURCE_KIND } from "@alpacakit/agents/config";
 import { jsonValueSchema } from "@alpacakit/core";
 import { z } from "zod";
-import { ADD_AGENT_CONFIG_RESULT, ADD_API_KEY_PROFILE_RESULT, LOGIN_MANAGED_HOME_RESULT, } from "./register.js";
 import { INVALID_NAME_RESULT_KIND } from "./names.js";
+import { ADD_AGENT_CONFIG_RESULT, ADD_API_KEY_PROFILE_RESULT, LOGIN_MANAGED_HOME_RESULT, } from "./register.js";
 import { REMOVE_AGENTS_HOME_ENTRY_RESULT } from "./remove.js";
 const RESULT_DISCRIMINATOR = "kind";
 const AVAILABILITY_DISCRIMINATOR = "status";