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

package/README.md

@@ -1,18 +1,28 @@
 # @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.
 
-**Experimental release candidate.** The repository currently uses Effect snapshot
-[`4e4a3a6`](https://pkg.pr.new/Effect-TS/effect/effect@4e4a3a6). The MCP adapter
-requires APIs missing from published `4.0.0-rc.115`, despite that being the current
-peer declaration. Until these versions are aligned, use the pinned snapshot;
-the declared peer version alone is not sufficient.
+## Install
+
+```sh
+pnpm add @gjermundgaraba/effect-actions@rc effect@4.0.0-rc.116
+```
+
+For Node server wiring:
+
+```sh
+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 { Action, ActionGroup, ActionHttp, ActionMcp } from "@gjermundgaraba/effect-actions";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 
 const Greet = Action.make("greet", {
   description: "Greet someone by name.",
@@ -21,84 +31,199 @@ const Greet = Action.make("greet", {
   mcp: { readOnly: true },
 });
 
-export const Actions = ActionGroup.make(Greet);
+export const Actions = ActionGroup.make({ name: "greetings" }, Greet);
+
+export const Http = ActionHttp.make({ apiPath: "/api/actions" }, Actions);
+
 const app = Actions.implement({
   greet: ({ name }) => Effect.succeed(`Hello, ${name}!`),
 });
 
 export const routes = Layer.mergeAll(
-  ActionHttp.layer(app, {
-    apiPath: "/api/actions",
-    openapiPath: "/openapi.json",
-  }),
-  ActionMcp.layer(app, { name: "greetings", version: "1.0.0", path: "/mcp" }),
+  Http.layer(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`,
-`GET /openapi.json`, and an MCP endpoint at `/mcp`. The HTTP response is
-`"Hello, Ada!"`; MCP returns `structuredContent: { value: "Hello, Ada!" }`.
+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!" }`; 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.
 
 ### Contracts
 
-- `input` defaults to `Action.NoInput` for actions without arguments.
-- `error` is a list of failure schemas, defaulting to none. Each schema retains
+- Omit `input` for an action without arguments.
+- `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 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.
-- 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`).
 
 ## HTTP client
 
 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 { ActionHttp } from "@gjermundgaraba/effect-actions";
-import { Actions } from "./quickstart.js";
+import { Http } from "./quickstart.js";
 
 export const greeting = Effect.gen(function* () {
-  const client = yield* ActionHttp.client(Actions, {
-    apiPath: "/api/actions",
-    baseUrl: "http://127.0.0.1:3000",
-  });
-  return yield* client.greet({ name: "Ada" });
+  const client = yield* HttpApiClient.make(Http.api, { baseUrl: "http://127.0.0.1:3000" });
+
+  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. 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
+
+An application can split its contracts and handlers into groups without splitting its
+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.layerHttp(
+    { protocols: [McpProtocol.v2026_07_28], name: "my-app", version: "1.0.0", path: "/mcp" },
+    UserApp,
+    AuditApp,
+  ),
+);
+```
+
+- **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. 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.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.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.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).
+
+## Serving the document
+
+`Http.api` is a native `HttpApi`, carrying every route, description, declared error and
+policy error. Documents and documentation UIs are therefore Effect's own:
+
+```ts
+import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiScalar, HttpApiSwagger, OpenApi } from "effect/unstable/httpapi";
+
+const documentation = Layer.mergeAll(
+  HttpRouter.add("GET", "/openapi.json", HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api))),
+  HttpApiSwagger.layer(Http.api, { path: "/docs" }),
+  HttpApiScalar.layer(Http.api, { path: "/reference" }),
+);
+```
+
+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                                                                                 |
-| ---------------------------- | --------------------------------------------------------------------------------------- |
-| `ActionHttp.layer`           | `apiPath`, `openapiPath`, `schemaError`                                                 |
-| `ActionHttp.api` / `openapi` | `apiPath`, `schemaError`                                                                |
-| `ActionHttp.client`          | `apiPath`, `schemaError`, `baseUrl`, `transformClient`, `transformResponse`             |
-| `ActionMcp.layer`            | `name`, `version`, `path`, `protocols`, `allowedOrigins`, `instructions`, `schemaError` |
+| 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`, `openapiPath` (on `layer` / `configure`), and MCP `path` are required —
-the library has no defaults. `ActionHttp.configure(options)` binds HTTP configuration
-for its `layer`, `api`, `openapi`, and `client` methods. Configured clients accept
-only connection options. Set `openapiPath: false` when the host serves a combined
-document.
+`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
@@ -118,53 +243,102 @@ vp run example
 ```
 
 `vp run dev` watches the library build. `vp check` also verifies the compile-time
-assertions in `tests/types.ts`. Tests cover both transports, official MCP clients,
-context isolation, schema-error policies, and cancellation.
+assertions in `tests/types.spec.ts`. Tests cover both transports, official MCP clients,
+request-context handling, schema-error policies, and cancellation.
 
-`vp run build` emits ESM and declarations into `dist/`. Public entry points are the
-package root, `/Action`, `/ActionGroup`, `/http`, `/mcp`, `/authentication`, `/testing`, and `/testing/client`.
-`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 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 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
 until the request scope closes. Downstream action errors are handled by their transport,
 not serialized as authentication failures.
 
-`ActionMcp.protectedResource({ resource, authorizationServers, scopesSupported })`
+`Authentication.protectedResource({ resource, authorizationServers, scopesSupported })`
 returns `{ layer, metadataUrl, challenge }`. Mount its public `layer` separately from
 protected routes. It publishes [RFC 9728 metadata](https://www.rfc-editor.org/rfc/rfc9728.html)
 at `/.well-known/oauth-protected-resource` followed by the resource path and query. Discovery
 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({
+  resource: "https://api.example.com/mcp",
+  authorizationServers: ["https://auth.example.com"],
+});
+
+// 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>
 
-## MCP testing
+    return Option.isNone(actor) ? yield* Effect.flip(unauthenticated) : actor.value;
+  }),
+);
+
+const routes = Layer.mergeAll(
+  discovery.layer,
+  protectedRoutes.pipe(Layer.provide(authentication.layer)),
+);
+```
+
+## Testing
 
-Import `mcpRequest` from `@gjermundgaraba/effect-actions/testing`; it requires no MCP client dependency.
-Import `withMcpClient` from `@gjermundgaraba/effect-actions/testing/client` and install
-its optional peer `@modelcontextprotocol/client@^2.0.0`. Only the client entry point loads this peer.
+Import from `@gjermundgaraba/effect-actions/Testing`; it requires no MCP client dependency.
+`withMcpClient` lives in `@gjermundgaraba/effect-actions/TestingClient` and needs the optional
+peer `@modelcontextprotocol/client@^2.0.0`. Only that entry point loads the peer.
+
+```ts
+const web = HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices)));
+
+const greeting = Effect.gen(function* () {
+  const client = yield* httpClient(Http.api, web.handler);
+
+  return yield* client.greetings.greet({ payload: { name: "Ada" } });
+});
+```
 
-- `mcpRequest(method, params?, { url, headers? })` builds a stateless 2026-07-28 request.
-  `url` is required. Caller `params._meta` fields override the default client capabilities
+- `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
+  send malformed arguments.
+  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, async client => ..., { path, mode?, baseUrl?, headers? })`
-  connects the official client and closes it in a `finally` block. `path` is required.
-  `mode` defaults to `"modern"` (2026-07-28); use `"legacy"` to exercise session negotiation.
+- `withMcpClient({ fetch, path, versionNegotiation?, baseUrl?, headers? }, async client => ...)`
+  connects the official client and closes it in a `finally` block.
+  `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,54 +1,62 @@
 import { Effect, Schema } from "effect";
 declare namespace Action_d_exports {
-  export { Action, Any, Codec, Handler, McpOptions, NoInput, Options, SchemaErrorPolicy, SchemaFailure, make };
+  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>;
-/** Failed request decoding or successful-result encoding, independent of transport terminology. */
-export interface SchemaFailure {
-  readonly phase: "input" | "output";
-  /** May contain sensitive values. Do not reflect it in public error messages. */
-  readonly cause: Schema.SchemaError;
-}
-/** Pure application-owned mapping, shared by the HTTP and MCP adapters. */
-export interface SchemaErrorPolicy<Errors extends ReadonlyArray<Codec>> {
-  readonly errors: Errors;
-  readonly map: (failure: SchemaFailure) => NoInfer<Errors[number]["Type"]>;
-}
+/** 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;
-  /** Defaults to `!readOnly`; the MCP spec only defines it for non-read-only tools. */
+  /** `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;
 }
-export interface Options<Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Http extends boolean = 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;
-  /** Defaults to `NoInput`. */
+  /** 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 error?: Errors;
+  readonly errors?: Errors;
+  /** `false` hides the action from HTTP routes and clients. */
   readonly http?: Http;
-  readonly mcp?: false | McpOptions;
+  /** `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> {
+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: false | {
-    readonly name: string;
-    readonly readOnly: boolean;
-    readonly destructive: boolean;
-  };
+  readonly mcp: ResolvedMcp<Name, Mcp>;
 }
-export type Any = Action<string, Codec, Codec, ReadonlyArray<Codec>>;
+/** 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. */
-export declare const NoInput: Schema.$Record<Schema.String, Schema.Never>;
-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>(name: Name, options: Options<Input, Output, Errors, Http>): Action<Name, Input, Output, Errors, Http>;
+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 as t };
+export { Action_d_exports };

package/dist/Action.mjs

@@ -1,30 +1,29 @@
-import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { assertName } from "./internal/actions.mjs";
 import { Schema } from "effect";
 //#region src/Action.ts
-var Action_exports = /* @__PURE__ */ __exportAll({
-	NoInput: () => NoInput,
-	make: () => make
-});
 /** 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}`);
+	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,
 		input: options.input ?? NoInput,
 		success: options.success,
-		errors: options.error ?? [],
+		errors: options.errors ?? [],
 		http: options.http !== false,
 		mcp
 	};
 }
 //#endregion
-export { NoInput, make, Action_exports as t };
+export { make };

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 };