@gjermundgaraba/effect-actions 0.1.0-rc.1 → 0.1.0-rc.2

package/README.md

@@ -1,31 +1,23 @@
 # @gjermundgaraba/effect-actions
 
-Define an Effect action once, implement it once, expose it over **HTTP and MCP**.
+Define an Effect action once, implement it once, and expose it through **HTTP, MCP, native Effect Toolkits, and CLIs**. Export an offline JSON catalog from the same contracts.
 
-**Snapshot-dependent preview.** This release requires Effect snapshot
-[`9ad9891`](https://pkg.pr.new/Effect-TS/effect/effect@9ad9891). The published npm
-version `effect@4.0.0-rc.115` is not compatible: it lacks APIs required by the MCP
-adapter. Install both packages explicitly:
+## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions@rc \
-  'effect@https://pkg.pr.new/Effect-TS/effect/effect@9ad9891'
+pnpm add @gjermundgaraba/effect-actions@rc effect@4.0.0-rc.116
 ```
 
-The snapshot reports version `4.0.0-rc.115`, so the package retains that nominal
-peer declaration. A semver peer cannot distinguish the snapshot from the npm
-build; satisfying the peer declaration alone does **not** ensure compatibility.
-Installation requires access to `pkg.pr.new`, not just the npm registry.
-
-For Node server wiring, use the matching platform snapshot too:
+For Node server wiring:
 
 ```sh
-pnpm add '@effect/platform-node@https://pkg.pr.new/Effect-TS/effect/@effect/platform-node@9ad9891'
+pnpm add @effect/platform-node@4.0.0-rc.116
 ```
 
 ## Quickstart
 
 ```ts
+import { McpProtocol } from "effect/unstable/ai";
 import { Effect, Layer, Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
@@ -49,13 +41,17 @@ const app = Actions.implement({
 
 export const routes = Layer.mergeAll(
   Http.layer(app),
-  ActionMcp.layer({ name: "greetings", version: "1.0.0", path: "/mcp" }, app),
+  ActionMcp.layerHttp(
+    { protocols: [McpProtocol.v2026_07_28], name: "greetings", version: "1.0.0", path: "/mcp" },
+    app,
+  ),
 );
 ```
 
-Serve `routes` with Effect's `HttpRouter`. This creates `POST /api/actions/greet` and an
+Serve `routes` with Effect's `HttpRouter`. This creates `POST /api/actions/greetings/greet` and an
 MCP endpoint at `/mcp`. The HTTP response is `"Hello, Ada!"`; MCP returns
-`structuredContent: { value: "Hello, Ada!" }`.
+`structuredContent: { value: "Hello, Ada!" }`; a declared error is an `isError` result
+whose text is the same JSON encoding HTTP sends as the body.
 See [examples/server.ts](examples/server.ts) for Node server wiring and the
 [authenticated demo](examples/README.md) for a runnable application.
 
@@ -65,14 +61,19 @@ See [examples/server.ts](examples/server.ts) for Node server wiring and the
 - `errors` is a list of failure schemas, defaulting to none. Each schema retains
   its own `httpApiStatus` annotation.
 - A group's `errors` are added to every one of its actions, so a shared set, such as
-  authorization failures, is declared once. Its `schemaError` policy decides how both
-  transports answer failed decoding or encoding; see
+  authorization failures, is declared once. Its `schemaError` policy decides how HTTP
+  answers failed decoding or encoding; MCP keeps the native toolkit's answers. See
   [schema-error policies](docs/behavior.md#schema-error-policies).
 - Actions default to both transports; use `http: false` or `mcp: false` to opt out.
-  An action exposed on neither is rejected.
-- MCP input must have an object-root JSON Schema; declared errors must encode to
-  objects. The MCP adapter checks this at Layer construction. HTTP allows scalars.
-- `mcp.name` overrides the tool name. `destructive` defaults to `!readOnly`.
+  Actions disabled on both remain available for explicitly mounted local CLI commands.
+- Action and group names match `[A-Za-z0-9_-]+` and are not `then`, which
+  would make a client thenable.
+- MCP input must have an object-root JSON Schema; the MCP adapter checks this at Layer
+  construction. HTTP allows scalar input. Results and errors may be any shape: MCP wraps
+  results as `{ value }` and reports errors as text, the protocol's own error channel.
+- `mcp.name` overrides the tool name (at most 128 characters). Tool hints default to
+  `readOnly: false`, `destructive: !readOnly`, `idempotent: false`, and `openWorld: true`.
+  Hints do not enforce authorization, approval, or retries.
 - Schemas must be service-free. Handlers may require services.
 - The group name is the OpenAPI tag and operation-ID prefix (`greetings.greet`).
 
@@ -81,22 +82,24 @@ See [examples/server.ts](examples/server.ts) for Node server wiring and the
 Save the quickstart above as `quickstart.ts`. Once its routes are served:
 
 ```ts
+import { HttpApiClient } from "effect/unstable/httpapi";
 import { Effect } from "effect";
 import { FetchHttpClient } from "effect/unstable/http";
 import { Http } from "./quickstart.js";
 
 export const greeting = Effect.gen(function* () {
-  const client = yield* Http.client({ baseUrl: "http://127.0.0.1:3000" });
+  const client = yield* HttpApiClient.make(Http.api, { baseUrl: "http://127.0.0.1:3000" });
 
-  return yield* client.greet({ name: "Ada" });
+  return yield* client.greetings.greet({ payload: { name: "Ada" } });
 }).pipe(Effect.provide(FetchHttpClient.layer));
 ```
 
-Run `greeting` with `Effect.runPromise`. Methods take decoded inputs and return
-decoded results; MCP-only actions are excluded. `ActionHttp.make` binds the mount path the
-server and its clients must agree on, so `client` accepts only connection options. Authentication headers can be added with
-`transformClient`. See [client details](docs/behavior.md#http-client-details)
-for error types, optional inputs, and native grouped clients.
+Run `greeting` with `Effect.runPromise`. Use Effect's native `HttpApiClient.make(Http.api,
+options)`: methods are grouped by action group and take explicit `{ payload: ... }`
+arguments, including `{ payload: {} }` for no-input actions. Inputs and results are
+decoded values; MCP-only actions are excluded. HTTP paths include the group: `<apiPath>/<group>/<action>`.
+Authentication headers can be added with `transformClient`. See
+[client details](docs/behavior.md#http-client-details) for error types and response modes.
 
 ## Multiple groups
 
@@ -104,28 +107,35 @@ An application can split its contracts and handlers into groups without splittin
 endpoints. Configuration comes first, then the groups or implementations:
 
 ```ts
+import { McpProtocol } from "effect/unstable/ai";
+
 const Http = ActionHttp.make({ apiPath: "/api/actions" }, PublicActions, UserActions);
 
 const routes = Layer.mergeAll(
   Http.layer(PublicApp),
   Http.layer(UserApp).pipe(Layer.provide(authentication.layer)),
-  ActionMcp.layer({ name: "my-app", version: "1.0.0", path: "/mcp" }, UserApp, AuditApp),
+  ActionMcp.layerHttp(
+    { protocols: [McpProtocol.v2026_07_28], name: "my-app", version: "1.0.0", path: "/mcp" },
+    UserApp,
+    AuditApp,
+  ),
 );
 ```
 
-- **One layer per group.** `Http.layer(app)` registers the routes of one group, and router
+- **Explicit mounting.** `Http.layer(...apps)` registers the routes of the supplied groups, and router
   middleware provided to a layer applies to that layer alone: above, only the user group
-  requires authentication. A group that is never mounted has no routes.
+  requires authentication. Use separate calls when groups need different middleware. A group that is never mounted has no routes.
 - **Each adapter reads only what it serves.** A group without HTTP actions registers nothing
-  and is not built by `Http.layer`, nor one without tools by `ActionMcp.layer`.
-- **Names.** Routes and client methods are flat (`POST /api/actions/<action>`,
-  `client.<action>()`), so group names and HTTP action names must be unique within one
-  `ActionHttp.make`, and tool names within one `ActionMcp.layer`. Duplicates throw at
-  construction; neither adapter looks at the other's names.
+  and is not built by `Http.layer`, nor one without tools by `ActionMcp.layerHttp`.
+- **Names.** Routes are `POST /api/actions/<group>/<action>`, and native client methods
+  are `client.<group>.<action>({ payload: ... })`. Group names must be unique within
+  `ActionHttp.make`; action names need only be unique within their group. Tool names
+  must be unique within each Toolkit or MCP projection. Adapters validate the
+  namespaces they serve, not another transport's names.
 - **MCP middleware is per endpoint.** An MCP endpoint is one route, so middleware provided
-  to `ActionMcp.layer`, authentication included, covers all of its tools. Handlers can still
+  to `ActionMcp.layerHttp`, authentication included, covers all of its tools. Handlers can still
   authorize each tool differently. Only tools that need different middleware, such as none
-  at all, need their own endpoint: one `ActionMcp.layer` per `path`.
+  at all, need their own endpoint: one `ActionMcp.layerHttp` per `path`.
 
 Each group is its own native `HttpApiGroup`, so a host can also combine separately made
 `Http.api` values with `HttpApi.addHttpApi`. See [examples/app.ts](examples/app.ts).
@@ -149,27 +159,71 @@ const documentation = Layer.mergeAll(
 Each is an ordinary route layer, so it takes whatever middleware it is provided. The same
 value gives Effect's grouped client: `HttpApiClient.make(Http.api)`.
 
+## More projections
+
+The same implementation can be used without an HTTP server:
+
+```ts
+import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
+import * as ActionCatalog from "@gjermundgaraba/effect-actions/ActionCatalog";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import * as ActionCliClient from "@gjermundgaraba/effect-actions/ActionCliClient";
+import { Argument } from "effect/unstable/cli";
+
+// Using Actions, Http, and app from the quickstart:
+const tools = ActionToolkit.make(app); // { toolkit, layer }, native Effect Toolkit
+const catalog = ActionCatalog.make(Actions); // JSON-serializable; no handlers acquired
+const command = ActionCli.group(app); // greetings greet --input '{"name":"Ada"}'
+const local = ActionCli.command(app, "greet", {
+  parameters: { name: Argument.String("name") },
+  input: ({ name }) => ({ name }),
+}); // greet Ada
+const remote = ActionCliClient.command(Http, "greetings", "greet"); // host supplies HttpClient
+```
+
+- **Toolkit:** MCP-enabled actions become native tools with their declared names and
+  hints. Calls retain invocation-service requirements and return native results, not
+  MCP envelopes. See [examples/toolkit.ts](examples/toolkit.ts).
+- **MCP stdio:** `ActionMcp.layerStdio({ name, version, protocols }, ...apps)` runs a
+  subprocess server using a host-provided `Stdio` service and trusted process principal.
+  See [examples/mcp-stdio.ts](examples/mcp-stdio.ts). Stdout is protocol-only.
+- **Catalog:** standalone input/output/error JSON schemas with local `$defs`, plus
+  metadata and group-qualified identities. See [examples/catalog.ts](examples/catalog.ts).
+- **Local CLI:** `.command(app, "actionName", options?)` selects one action; `.group(app,
+options?)` selects a group, including local-only actions. The host supplies services.
+- **Remote CLI:** `ActionCliClient` projects HTTP contracts into commands using native
+  `HttpApiClient`; it never executes local handlers or manages credentials. See
+  [examples/cli.ts](examples/cli.ts) and [examples/cli-client.ts](examples/cli-client.ts).
+
+Generated CLI commands accept whole-input `--input '<json>'`. For a human-oriented
+command, supply native Effect flags/arguments through `parameters` and map them to
+encoded action input with `input`. Explicitly configured commands do not also accept
+`--input`; their syntax is independent of schema changes. Commands print validated
+JSON by default; an optional renderer enables human output with `--json` available.
+See [CLI boundaries](docs/behavior.md#cli-boundaries) for codecs and configuration.
+
 ## Adapter options
 
-| API                                   | Options                                                                  |
-| ------------------------------------- | ------------------------------------------------------------------------ |
-| `ActionGroup.make(options, …actions)` | `name`, `errors`, `schemaError`                                          |
-| `ActionHttp.make(options, …groups)`   | `apiPath`                                                                |
-| `Http.layer(app)`                     | None                                                                     |
-| `Http.client(options?)`               | `baseUrl`, `transformClient`, `transformResponse`                        |
-| `ActionMcp.layer(options, …apps)`     | `name`, `version`, `path`, `protocols`, `allowedOrigins`, `instructions` |
+| API                                    | Options                                                                  |
+| -------------------------------------- | ------------------------------------------------------------------------ |
+| `ActionGroup.make(options, …actions)`  | `name`, `errors`, `schemaError`                                          |
+| `ActionHttp.make(options, …groups)`    | `apiPath`                                                                |
+| `Http.layer(...apps)`                  | None                                                                     |
+| `ActionMcp.layerHttp(options, …apps)`  | `name`, `version`, `path`, `protocols`, `allowedOrigins`, `instructions` |
+| `ActionMcp.layerStdio(options, …apps)` | `name`, `version`, `protocols`, `instructions`                           |
 
-`apiPath` and MCP `path` have no defaults. `Http` has three members: `api`, `layer` and
-`client`.
+`apiPath` and MCP `path` have no defaults. `Http` has two members: `api` and `layer`. MCP `protocols` is required and takes Effect’s native `McpProtocol` adapters.
+Effect owns protocol negotiation and sessions.
 
 See [adapter behavior](docs/behavior.md) for shared schema-error policies,
 dependency lifetimes, wire formats, and MCP protocol support.
 
 ## Scope
 
-HTTP means JSON POST endpoints, not Effect's RPC wire protocol. Both adapters use
-Effect's servers; there is no MCP SDK runtime dependency. Actions are unary:
-no streaming, uploads, prompts, resources, or retries.
+HTTP means JSON POST endpoints, not Effect's RPC wire protocol. HTTP and MCP use
+Effect's servers: `HttpApi` and one `McpServer` `Tool` per action; there is no MCP SDK
+runtime dependency. Actions are unary:
+no streaming, uploads, prompts, resources, retries, or code-execution sandbox.
 
 Authentication and authorization belong to the application. Tool discovery is
 not filtered by actor. The example's bearer tokens are **demo-only**; production
@@ -190,25 +244,30 @@ vp run example
 
 `vp run dev` watches the library build. `vp check` also verifies the compile-time
 assertions in `tests/types.spec.ts`. Tests cover both transports, official MCP clients,
-context isolation, schema-error policies, and cancellation.
+request-context handling, schema-error policies, and cancellation.
 
-`vp run build` emits ESM and declarations into `dist/`. The entry points are one subpath per
-module: `/Action`, `/ActionGroup`, `/ActionHttp`, `/ActionMcp`, `/Authentication`, `/Testing`,
-and `/TestingClient`. There is no package root, so a contracts-only or browser bundle never
+`vp run build` emits module-preserving ESM and declarations into `dist/`. The entry points
+are one subpath per module: `/Action`, `/ActionGroup`, `/ActionHttp`, `/ActionMcp`,
+`/ActionToolkit`, `/ActionCatalog`, `/ActionCli`, `/ActionCliClient`, `/Authentication`,
+`/Testing`, and `/TestingClient`. There is no package root, so a contracts-only or browser bundle never
 loads the MCP server or the optional client peer.
-`vp run test:package` builds and checks a tarball in an isolated consumer using the pinned
-Effect snapshot; it does not establish compatibility with the published peer.
+`vp run test:package` builds and checks a tarball in an isolated consumer with
+`skipLibCheck: false`.
 
 ## Authentication and OAuth discovery
 
-`Authentication.middleware(CurrentActor, { authenticate, errors, headers })` provides
-an application-defined context service for each request. `authenticate` is an Effect;
-`errors` lists its error schemas in precedence order. The first matching schema owns
-both serialization and `httpApiStatus` (500 when unannotated). If its encoder fails,
-the request fails as a server error; another schema is not tried. `headers(error)`
-can add a Bearer challenge.
-Responses use `Cache-Control: no-store`, including failures handled by enclosing middleware. Provide the returned middleware's `.layer` to
-HTTP and MCP route layers. See [examples/app.ts](examples/app.ts).
+`Authentication.middleware(CurrentActor, authenticate)` provides an application-defined
+context service for each request. `authenticate` is an Effect that succeeds with the
+identity or fails with the `HttpServerResponse` to send instead, so the host owns the
+status, body and any Bearer challenge: `HttpServerResponse.schemaJson(Unauthenticated)(error,
+{ status: 401, headers })`. Responses use `Cache-Control: no-store`, including failures handled
+by enclosing middleware. Provide the returned middleware's `.layer` to HTTP and MCP route
+layers. See [examples/app.ts](examples/app.ts).
+
+Use distinct service tags for startup capabilities and request identities. Never supply
+`CurrentActor` or other request-identity tags through startup layers or root context:
+native Effect context capture can shadow request values or supply missing runtime values.
+The adapters do not provide an additional context-isolation boundary.
 
 Authentication dependencies are request requirements, as with native `HttpRouter.middleware`.
 Use `.combine(...)` with middleware that provides them. Acquired resources stay alive
@@ -222,11 +281,11 @@ at `/.well-known/oauth-protected-resource` followed by the resource path and que
 matches that literal path and query for GET and HEAD; other requests reach the host router.
 Caching policy belongs to the host. `challenge()`
 returns the `WWW-Authenticate` value; pass `{ error: "invalid_token" }` or
-`{ error: "insufficient_scope", scope: "admin" }` where appropriate. Supported scopes
-are advertised in metadata; the challenge names only scopes needed for that request.
-The helper supports HTTPS URLs and loopback HTTP for development, with no credentials
-or fragment. Resource identifiers may include a query; authorization-server issuers may not.
-Your application owns login, consent, and token verification.
+`{ error: "insufficient_scope", scope: "admin" }` where appropriate. Parameter values are
+quoted and escaped, never rejected. Supported scopes are advertised in metadata; the
+challenge names only scopes needed for that request. The helper publishes what it is given:
+your deployment is responsible for these being valid OAuth URLs (HTTPS, or loopback HTTP in
+development), and your application owns login, consent, and token verification.
 
 ```ts
 const discovery = Authentication.protectedResource({
@@ -234,11 +293,20 @@ const discovery = Authentication.protectedResource({
   authorizationServers: ["https://auth.example.com"],
 });
 
-const authentication = Authentication.middleware(CurrentActor, {
-  authenticate,
-  errors: [Unauthenticated],
-  headers: () => ({ "www-authenticate": discovery.challenge({ error: "invalid_token" }) }),
-});
+// The response sent when authentication fails; the host owns status, body and challenge.
+const unauthenticated = HttpServerResponse.schemaJson(Unauthenticated)(
+  new Unauthenticated({ message: "A bearer token is required." }),
+  { status: 401, headers: { "www-authenticate": discovery.challenge({ error: "invalid_token" }) } },
+).pipe(Effect.orDie);
+
+const authentication = Authentication.middleware(
+  CurrentActor,
+  Effect.gen(function* () {
+    const actor = yield* verifyToken; // Effect<Option<Actor>, never, HttpServerRequest>
+
+    return Option.isNone(actor) ? yield* Effect.flip(unauthenticated) : actor.value;
+  }),
+);
 
 const routes = Layer.mergeAll(
   discovery.layer,
@@ -256,13 +324,13 @@ peer `@modelcontextprotocol/client@^2.0.0`. Only that entry point loads the peer
 const web = HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices)));
 
 const greeting = Effect.gen(function* () {
-  const client = yield* httpClient(Http, web.handler);
+  const client = yield* httpClient(Http.api, web.handler);
 
-  return yield* client.greet({ name: "Ada" });
+  return yield* client.greetings.greet({ payload: { name: "Ada" } });
 });
 ```
 
-- `httpClient(Http, handler, options?)` is the typed HTTP client calling a web handler in
+- `httpClient(Http.api, handler, options?)` is the native grouped HTTP client calling a web handler in
   memory. `options` are the client's connection options; `baseUrl` defaults to `http://localhost`.
 - `mcpRequest({ url, method, params?, headers? })` builds a stateless 2026-07-28 request.
   `params` takes whatever `JSON.stringify` accepts, `undefined` fields included, so tests can
@@ -270,6 +338,7 @@ const greeting = Effect.gen(function* () {
   Caller `params._meta` fields override the default client capabilities
   and information; application metadata is preserved. The protocol version stays pinned to
   2026-07-28 in both the request header and metadata. Metadata is merged shallowly.
-- `withMcpClient({ fetch, path, mode?, baseUrl?, headers? }, async client => ...)`
+- `withMcpClient({ fetch, path, versionNegotiation?, baseUrl?, headers? }, async client => ...)`
   connects the official client and closes it in a `finally` block.
-  `mode` defaults to `"modern"` (2026-07-28); use `"legacy"` to exercise session negotiation.
+  `versionNegotiation` is passed directly to the official client (whose default is legacy).
+  For a stateless endpoint, pass `versionNegotiation: { mode: { pin: "2026-07-28" } }`.

package/dist/Action.d.mts

@@ -1,2 +1,62 @@
-import { a as Handler, c as SchemaErrorPolicy, i as Codec, l as SchemaFailure, o as McpOptions, r as Any, s as Options, t as Action, u as make } from "./Action-CXsfTEhx.mjs";
-export { Action, Any, Codec, Handler, McpOptions, Options, SchemaErrorPolicy, SchemaFailure, make };
+import { Effect, Schema } from "effect";
+declare namespace Action_d_exports {
+  export { Action, Any, Codec, Handler, McpOptions, Options, make };
+}
+/** Any service-free schema. Only handlers may require services. */
+export type Codec = Schema.Codec<unknown, unknown, never, never>;
+/** MCP tool metadata; every field has a default derived from the action. */
+export interface McpOptions {
+  /** Tool name; defaults to the action name. Must match `^[A-Za-z0-9_-]{1,128}$`. */
+  readonly name?: string;
+  /** `readOnlyHint`; defaults to `false`. */
+  readonly readOnly?: boolean;
+  /** `destructiveHint`; defaults to `!readOnly`, as the MCP spec only defines it for writes. */
+  readonly destructive?: boolean;
+  /** `idempotentHint`; defaults to `false`. */
+  readonly idempotent?: boolean;
+  /** `openWorldHint`; defaults to `true`. */
+  readonly openWorld?: boolean;
+}
+type ResolvedMcp<Name extends string, Mcp extends false | McpOptions | undefined> = Mcp extends false ? false : {
+  readonly name: Mcp extends McpOptions ? "name" extends keyof Mcp ? Extract<Mcp["name"], string> extends never ? Name : Extract<Mcp["name"], string> | (undefined extends Mcp["name"] ? Name : never) : Name : Name;
+  readonly readOnly: boolean;
+  readonly destructive: boolean;
+  readonly idempotent: boolean;
+  readonly openWorld: boolean;
+};
+/** What `make` needs to define an action. */
+export interface Options<Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Http extends boolean = boolean, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
+  readonly description: string;
+  /** Omit for an action without arguments. */
+  readonly input?: Input;
+  readonly success: Output;
+  /** One schema per declared failure; each keeps its own HTTP status annotation. Defaults to none. */
+  readonly errors?: Errors;
+  /** `false` hides the action from HTTP routes and clients. */
+  readonly http?: Http;
+  /** `false` hides the action from MCP; otherwise tool metadata. */
+  readonly mcp?: Mcp;
+}
+/** A pure contract: schemas and transport metadata. Implementations are bound by `ActionGroup.implement`. */
+export interface Action<Name extends string, Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Http extends boolean = boolean, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
+  readonly name: Name;
+  readonly description: string;
+  readonly input: Input;
+  readonly success: Output;
+  readonly errors: Errors;
+  readonly http: Http;
+  readonly mcp: ResolvedMcp<Name, Mcp>;
+}
+/** Any action, with its schemas erased. */
+export type Any = Action<string, Codec, Codec, ReadonlyArray<Codec>, boolean, false> | Action<string, Codec, Codec, ReadonlyArray<Codec>, boolean, McpOptions> | Action<string, Codec, Codec, ReadonlyArray<Codec>, boolean, undefined>;
+/** Receives decoded input; may fail only with the declared errors. */
+export type Handler<A extends Any, R = never> = (input: A["input"]["Type"]) => Effect.Effect<A["success"]["Type"], A["errors"][number]["Type"], R>;
+/** An empty object schema that also produces the object root MCP requires. */
+declare const NoInput: Schema.$Record<Schema.String, Schema.Never>;
+/**
+ * Define an action contract. Names are `[A-Za-z0-9_-]+`, other than `then`.
+ * Actions can be local-only by setting both transports to `false`.
+ */
+export declare function make<const Name extends string, Input extends Codec = typeof NoInput, Output extends Codec = never, const Errors extends ReadonlyArray<Codec> = [], const Http extends boolean = true, const Mcp extends false | McpOptions | undefined = undefined>(name: Name, options: Options<Input, Output, Errors, Http, Mcp>): Action<Name, Input, Output, Errors, Http, Mcp>;
+//#endregion
+export { Action_d_exports };

package/dist/Action.mjs

@@ -1,17 +1,20 @@
+import { assertName } from "./internal/actions.mjs";
 import { Schema } from "effect";
 //#region src/Action.ts
 /** An empty object schema that also produces the object root MCP requires. */
 const NoInput = Schema.Record(Schema.String, Schema.Never);
 function make(name, options) {
-	if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) throw new Error(`Invalid action name: ${name}`);
-	if (options.http === false && options.mcp === false) throw new Error(`Action ${name} is exposed on no transport`);
+	assertName("action name", name);
 	const readOnly = options.mcp === false ? false : options.mcp?.readOnly ?? false;
 	const mcp = options.mcp === false ? false : {
 		name: options.mcp?.name ?? name,
 		readOnly,
-		destructive: options.mcp?.destructive ?? !readOnly
+		destructive: options.mcp?.destructive ?? !readOnly,
+		idempotent: options.mcp?.idempotent ?? false,
+		openWorld: options.mcp?.openWorld ?? true
 	};
-	if (mcp !== false && !/^[A-Za-z0-9_-]{1,128}$/.test(mcp.name)) throw new Error(`Invalid MCP name: ${mcp.name}`);
+	if (mcp !== false && mcp.name.length > 128) throw new Error(`Invalid MCP name: ${mcp.name}`);
+	if (mcp !== false) assertName("MCP name", mcp.name);
 	return {
 		name,
 		description: options.description,

package/dist/ActionCatalog.d.mts

@@ -0,0 +1,31 @@
+import { Action_d_exports, Any } from "./Action.mjs";
+import { ActionGroup_d_exports, Any as Any$1 } from "./ActionGroup.mjs";
+import { JsonSchema } from "effect";
+//#region src/ActionCatalog.d.ts
+/** One contract, with independently rooted JSON schemas for its encoded values. */
+export interface Entry {
+  readonly id: string;
+  readonly group: string;
+  readonly name: string;
+  readonly description: string;
+  readonly http: boolean;
+  readonly mcp: Any["mcp"];
+  readonly input: JsonSchema.JsonSchema;
+  readonly success: JsonSchema.JsonSchema;
+  /** Includes the errors inherited from the group; not HTTP schema-policy errors. */
+  readonly errors: ReadonlyArray<JsonSchema.JsonSchema>;
+  /** HTTP-only decoding/encoding policy errors, separate from handler failures. */
+  readonly httpSchemaErrors: ReadonlyArray<JsonSchema.JsonSchema>;
+}
+/** An offline contract document, not an authorization decision or a mounted endpoint. */
+export interface Catalog {
+  readonly version: "1";
+  readonly actions: ReadonlyArray<Entry>;
+}
+/**
+ * Describe the supplied groups without acquiring implementations. Schemas describe
+ * encoded action values, not MCP's `{ value }` envelope or deployment-specific URLs.
+ * Local-only actions are included; the host chooses what, if anything, to publish.
+ */
+export declare const make: (...groups: ReadonlyArray<Any$1>) => Catalog;
+//#endregion

package/dist/ActionCatalog.mjs

@@ -0,0 +1,36 @@
+import { assertDistinct } from "./internal/actions.mjs";
+import { JsonSchema, Schema } from "effect";
+//#region src/ActionCatalog.ts
+const jsonSchema = (codec) => {
+	const document = Schema.toJsonSchemaDocument(codec);
+	return {
+		$schema: JsonSchema.META_SCHEMA_URI_DRAFT_2020_12,
+		...document.schema,
+		...Object.keys(document.definitions).length === 0 ? {} : { $defs: document.definitions }
+	};
+};
+/**
+* Describe the supplied groups without acquiring implementations. Schemas describe
+* encoded action values, not MCP's `{ value }` envelope or deployment-specific URLs.
+* Local-only actions are included; the host chooses what, if anything, to publish.
+*/
+const make = (...groups) => {
+	assertDistinct("catalog group", groups.map((group) => group.name));
+	return {
+		version: "1",
+		actions: groups.flatMap((group) => group.actions.map((action) => ({
+			id: `${group.name}.${action.name}`,
+			group: group.name,
+			name: action.name,
+			description: action.description,
+			http: action.http,
+			mcp: action.mcp,
+			input: jsonSchema(action.input),
+			success: jsonSchema(action.success),
+			errors: action.errors.map(jsonSchema),
+			httpSchemaErrors: action.http ? group.schemaError?.errors.map(jsonSchema) ?? [] : []
+		})))
+	};
+};
+//#endregion
+export { make };

package/dist/ActionCli.d.mts

@@ -0,0 +1,27 @@
+import { Action_d_exports, Any, Handler } from "./Action.mjs";
+import { Actions } from "./internal/actions.mjs";
+import { HandlerContext, Handlers, HandlersContext, Implementation } from "./internal/implementation.mjs";
+import { Options } from "./internal/cli.mjs";
+import { Scope } from "effect";
+import { Command } from "effect/unstable/cli";
+//#region src/ActionCli.d.ts
+/** Configuration for an aggregate group command. */
+export interface GroupOptions {
+  /** Override the group command name. */
+  readonly name?: string;
+}
+type Selected<G extends Actions, Name extends G["actions"][number]["name"]> = Extract<G["actions"][number], {
+  readonly name: Name;
+}>;
+type BoundHandler<Name extends string, A extends Any, R> = Readonly<Record<Name, Handler<A, R>>>;
+/**
+ * Project one explicitly selected local action into a native Effect CLI command.
+ * The action name resolves against the bound group; no HTTP fallback exists.
+ */
+export declare const command: <G extends Actions, Name extends G["actions"][number]["name"], H extends BoundHandler<Name, Selected<G, Name>, HandlerContext<H, Name>>, EX, RX, Parameters extends Command.Command.Config = never>(app: Implementation<G, H, EX, RX>, name: Name, options?: Options<Selected<G, Name>["success"]["Type"], Parameters>) => Command.Command<string, never, {}, EX | import("effect/Schema").SchemaError | Extract<G["actions"][number], {
+  readonly name: Name;
+}>["errors"][number]["Type"], Exclude<RX, Scope.Scope> | Exclude<HandlerContext<H, Name>, Scope.Scope>>;
+/** Project every local action below its group namespace with default CLI options. */
+export declare const group: <G extends Actions, H extends Handlers<HandlersContext<H>>, EX, RX>(app: Implementation<G, H, EX, RX>, options?: GroupOptions) => Command.Command<string, {}, {}, EX | import("effect/Schema").SchemaError | G["actions"][number]["errors"][number]["Type"], Exclude<Exclude<RX, Scope.Scope>, Command.CommandContext<string>> | Exclude<Exclude<HandlersContext<H>, Scope.Scope>, Command.CommandContext<string>>>;
+//#endregion
+export type { Options };

package/dist/ActionCli.mjs

@@ -0,0 +1,26 @@
+import { dispatch } from "./internal/implementation.mjs";
+import { command as command$1 } from "./internal/cli.mjs";
+import { Effect } from "effect";
+import { Command } from "effect/unstable/cli";
+//#region src/ActionCli.ts
+const select = (group, name) => {
+	const action = group.actions.find((candidate) => candidate.name === name);
+	if (action === void 0) throw new Error(`Unknown action "${group.name}.${name}"`);
+	return action;
+};
+const local = (app, action, input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers)(input)));
+/**
+* Project one explicitly selected local action into a native Effect CLI command.
+* The action name resolves against the bound group; no HTTP fallback exists.
+*/
+const command = (app, name, options) => {
+	const action = select(app.group, name);
+	return command$1(action, (input) => local(app, action, input), options);
+};
+/** Project every local action below its group namespace with default CLI options. */
+const group = (app, options) => {
+	const commands = app.group.actions.map((action) => command$1(action, (input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers)(input)))));
+	return Command.make(options?.name ?? app.group.name).pipe(Command.withSubcommands(commands));
+};
+//#endregion
+export { command, group };

package/dist/ActionCliClient.d.mts

@@ -0,0 +1,45 @@
+import { Actions } from "./internal/actions.mjs";
+import { Options as Options$1 } from "./internal/cli.mjs";
+import { ActionHttp_d_exports, Api, Http } from "./ActionHttp.mjs";
+import { Effect } from "effect";
+import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+import { Command } from "effect/unstable/cli";
+import { HttpClient } from "effect/unstable/http";
+//#region src/ActionCliClient.d.ts
+/** Parsing, rendering and native HTTP-endpoint configuration for one remote action. */
+export type Options<Output, ParsedParameters extends Command.Command.Config = never> = Options$1<Output, ParsedParameters> & {
+  /** Passed directly to Effect's native `HttpApiClient.endpoint`. */
+  readonly connection?: NonNullable<globalThis.Parameters<typeof HttpApiClient.make>[1]>;
+};
+/** Configuration for a remote aggregate group command. */
+export interface GroupOptions {
+  /** Override the group command name. */
+  readonly name?: string;
+  /** Shared native HTTP-endpoint configuration for every remote action. */
+  readonly connection?: NonNullable<globalThis.Parameters<typeof HttpApiClient.make>[1]>;
+}
+type Group<Groups extends ReadonlyArray<Actions>, Name extends Groups[number]["name"]> = Extract<Groups[number], {
+  readonly name: Name;
+}>;
+type Selected<G extends Actions, Name extends G["actions"][number]["name"]> = Extract<G["actions"][number], {
+  readonly name: Name;
+}>;
+type HttpNames<G extends Actions> = Extract<G["actions"][number], {
+  readonly http: true;
+}>["name"];
+type ApiGroups<Groups extends ReadonlyArray<Actions>> = Api<Groups[number]> extends HttpApi.HttpApi<"actions", infer ApiGroups> ? ApiGroups : never;
+type Endpoint<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Extract<HttpApiGroup.EndpointsWithIdentifier<ApiGroups<Groups>, Extract<GroupName, HttpApiGroup.Identifier<ApiGroups<Groups>>>>, {
+  readonly identifier: ActionName;
+}>;
+type NativeMethod<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = HttpApiClient.Client.Method<Extract<Endpoint<Groups, GroupName, ActionName>, HttpApiEndpoint.ConstraintRequest>, never, never>;
+type RemoteCommand<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Command.Command<string, never, {}, Effect.Error<ReturnType<NativeMethod<Groups, GroupName, ActionName>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, GroupName, ActionName>>>>;
+type RemoteGroupCommand<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"]> = Command.Command<string, {}, {}, Effect.Error<ReturnType<NativeMethod<Groups, GroupName, HttpNames<Group<Groups, GroupName>>>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, GroupName, HttpNames<Group<Groups, GroupName>>>>>>;
+/**
+ * Project one HTTP action retained by the binding into a native Effect CLI command.
+ * Group and action selectors resolve exclusively from `http.groups`; runtime guards
+ * keep dynamically supplied selector strings from reaching the native client.
+ */
+export declare const command: <const Groups extends ReadonlyArray<Actions>, const GroupName extends Groups[number]["name"], const ActionName extends HttpNames<Group<Groups, GroupName>>, ParsedParameters extends Command.Command.Config = never>(http: Http<Groups>, groupName: GroupName, actionName: ActionName, options?: Options<Selected<Group<Groups, GroupName>, ActionName>["success"]["Type"], ParsedParameters>) => RemoteCommand<Groups, GroupName, ActionName>;
+/** Project all HTTP-enabled actions retained by one group below its group namespace. */
+export declare const group: <const Groups extends ReadonlyArray<Actions>, const GroupName extends Groups[number]["name"]>(http: Http<Groups>, groupName: GroupName, options?: GroupOptions) => RemoteGroupCommand<Groups, GroupName>;
+//#endregion