@gjermundgaraba/effect-actions 0.1.0 → 0.2.0

package/README.md

@@ -101,6 +101,10 @@ The `effect` peer is pinned to an exact Effect 4 release candidate and moves wit
 release of this package for each Effect release candidate it adopts. Actions are unary JSON over HTTP and MCP: no streaming, uploads, prompts, or resources.
 Authentication and authorization belong to the application. See [docs/setup.md](docs/setup.md).
 
+## Acknowledgements
+
+A few idea (like the native Toolkit, CLI, and catalog projections) are inspired by the excellent [rat-stack](https://github.com/joelhooks/rat-stack) by Joel Hooks.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed.

package/dist/ActionHttp.mjs

@@ -7,23 +7,35 @@ const httpActions = (group) => group.actions.filter((action) => action.http);
 const endpoint = (apiPath, group, action) => HttpApiEndpoint.post(action.name, `${apiPath}/${group.name}/${action.name}`, {
 	payload: action.input,
 	success: action.success,
-	error: [...action.errors, ...group.schemaError?.errors ?? []]
+	error: action.errors
 }).annotate(OpenApi.Description, action.description);
-function erasedApi(groups, options) {
-	const [first, ...rest] = groups.flatMap((group) => {
-		const [first, ...rest] = httpActions(group).map((action) => endpoint(options.apiPath, group, action));
-		return first === void 0 ? [] : [HttpApiGroup.make(group.name).add(first, ...rest)];
-	});
-	const empty = HttpApi.make("actions");
-	return first === void 0 ? empty : empty.add(first, ...rest);
-}
-const schemaErrorMiddleware = (policy) => {
-	class SchemaErrors extends HttpApiMiddleware.Service()("effect-actions/http/SchemaErrors", { error: policy.errors }) {}
+/** The native middleware declares the policy's errors on every endpoint it wraps. */
+const schemaErrorMiddleware = (name, policy) => {
+	class SchemaErrors extends HttpApiMiddleware.Service()(`effect-actions/http/SchemaErrors/${name}`, { error: policy.errors }) {}
 	return {
 		SchemaErrors,
 		layer: HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(policy.map(failure)))
 	};
 };
+function bind(options, group) {
+	const [first, ...rest] = httpActions(group).map((action) => endpoint(options.apiPath, group, action));
+	if (first === void 0) return void 0;
+	const native = HttpApiGroup.make(group.name).add(first, ...rest);
+	if (group.schemaError === void 0) return {
+		native,
+		policy: Layer.empty
+	};
+	const policy = schemaErrorMiddleware(group.name, group.schemaError);
+	return {
+		native: native.middleware(policy.SchemaErrors),
+		policy: policy.layer
+	};
+}
+function apiOf(groups) {
+	const [first, ...rest] = groups;
+	const empty = HttpApi.make("actions").annotate(HttpApi.ParseOptions, { errors: "all" });
+	return first === void 0 ? empty : empty.add(first, ...rest);
+}
 /**
 * `HttpApiBuilder.handleAll` registers a dynamically assembled record. The
 * action selected by the native router determines the input before `dispatch`
@@ -34,32 +46,33 @@ const schemaErrorMiddleware = (policy) => {
 const erasedHandlers = (handlers) => {
 	return handlers;
 };
-/** Build routes for one group. Handler erasure is limited to native dynamic endpoint registration. */
-const groupLayer = (options, app) => {
-	const actions = httpActions(app.group);
-	if (actions.length === 0) return Layer.empty;
-	const api = erasedApi([app.group], options);
-	const entries = (record) => Object.fromEntries(actions.map((action) => [action.name, (request) => dispatch(app.group, action, record)(request.payload)]));
-	const handlers = (record) => HttpApiBuilder.group(api, app.group.name, (builder) => builder.handleAll(entries(record)));
-	if (app.group.schemaError === void 0) return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.layer(api).pipe(Layer.provide(handlers(erasedHandlers(record))))));
-	const schemaErrors = schemaErrorMiddleware(app.group.schemaError);
-	const policyApi = api.middleware(schemaErrors.SchemaErrors);
-	const policyHandlers = (record) => HttpApiBuilder.group(policyApi, app.group.name, (builder) => {
-		const dynamicEntries = entries(record);
-		return builder.handleAll(dynamicEntries);
-	});
-	return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.layer(policyApi).pipe(Layer.provide(policyHandlers(erasedHandlers(record))), Layer.provide(schemaErrors.layer))));
+/** Register one group's handlers. Handler erasure is limited to native dynamic endpoint registration. */
+const groupHandlers = (api, app, policy) => {
+	const entries = (record) => Object.fromEntries(httpActions(app.group).map((action) => [action.name, (request) => dispatch(app.group, action, record)(request.payload)]));
+	return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.group(api, app.group.name, (builder) => builder.handleAll(entries(erasedHandlers(record)))))).pipe(Layer.provide(policy));
 };
 function make(options, ...groups) {
 	assertDistinct("action group", groups.map((group) => group.name));
+	const bound = new Map(groups.flatMap((group) => {
+		const binding = bind(options, group);
+		return binding === void 0 ? [] : [[group, binding]];
+	}));
 	const layer = (...apps) => {
 		assertDistinct("implementation group", apps.map((app) => app.group.name));
 		for (const app of apps) if (!groups.includes(app.group)) throw new Error(`Implementation of group "${app.group.name}" is not served by this adapter`);
-		return apps.map((app) => groupLayer(options, app)).reduce((all, app) => Layer.merge(all, app), Layer.empty);
+		const served = apps.flatMap((app) => {
+			const binding = bound.get(app.group);
+			return binding === void 0 ? [] : [{
+				app,
+				...binding
+			}];
+		});
+		const api = apiOf(served.map(({ native }) => native));
+		return served.reduce((layer, { app, policy }) => layer.pipe(Layer.provide(groupHandlers(api, app, policy))), HttpApiBuilder.layer(api));
 	};
 	return {
 		groups,
-		api: erasedApi(groups, options),
+		api: apiOf([...bound.values()].map(({ native }) => native)),
 		layer
 	};
 }

package/dist/ActionMcp.d.mts

@@ -1,6 +1,6 @@
 import { AnyImplementation, BuildContext, BuildError, RequestContext } from "./internal/implementation.mjs";
 import { Cause, Layer } from "effect";
-import { McpServer } from "effect/unstable/ai";
+import { McpSchema, McpServer } from "effect/unstable/ai";
 import { HttpRouter } from "effect/unstable/http";
 import { Stdio } from "effect/Stdio";
 //#region src/ActionMcp.d.ts
@@ -24,18 +24,20 @@ export interface StdioOptions {
   readonly protocols: Parameters<typeof McpServer.layerStdio>[0]["protocols"];
   readonly instructions?: string;
 }
+/** The native server supplies its own request context to every tool call. */
+type ToolRequestContext<App> = Exclude<RequestContext<App>, McpSchema.McpRequestContext>;
 /**
  * Serve MCP tools over one Streamable HTTP endpoint.
  *
  * Middleware provided around this layer has the normal HTTP lifetime. Native
  * context capture applies: never provide request-identity tags at startup.
  */
-export declare function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>>(options: Options, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", RequestContext<Apps[number]>>>;
+export declare function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>>(options: Options, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", ToolRequestContext<Apps[number]>>>;
 /**
  * Serve MCP tools through newline-delimited JSON-RPC on standard I/O.
  *
  * The host supplies the `Stdio` service. Arguments are tool input only and
  * never establish request identity or authority.
  */
-export declare function layerStdio<const Apps extends ReadonlyArray<AnyImplementation>>(options: StdioOptions, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | Stdio | RequestContext<Apps[number]>>;
+export declare function layerStdio<const Apps extends ReadonlyArray<AnyImplementation>>(options: StdioOptions, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | Stdio | ToolRequestContext<Apps[number]>>;
 //#endregion

package/dist/internal/tools.mjs

@@ -55,8 +55,9 @@ const assertMcpObjectInput = (action, tool) => {
 };
 const project = (projection, entry) => {
 	const tool = projection === "native" ? nativeTool(entry.action) : mcpTool(entry.action);
-	if (projection === "mcp") assertMcpObjectInput(entry.action, tool);
-	return tool;
+	if (projection === "native") return tool;
+	assertMcpObjectInput(entry.action, tool);
+	return tool.annotate(Tool.Strict, true);
 };
 const handler = (projection, app, action, handlers) => {
 	const run = (input) => dispatch(app.group, action, handlers)(input);

package/docs/Action.md

@@ -107,7 +107,7 @@ export const Double = Action.make("double", {
 - Hint defaults: `readOnly: false`, `destructive: !readOnly`, `idempotent: false`, `openWorld: true`. Hints are metadata for the model. They do not enforce authorization, approval, or retries.
 - Schemas must be service-free. Put service access in the handler.
 - The group name, not the action, is the OpenAPI tag and operation-ID prefix: `<group>.<action>`.
-- Object schemas strip excess fields on decode unless the schema is configured to reject them.
+- HTTP strips undeclared input fields. MCP tools are strict (`Tool.Strict`): undeclared arguments are an invalid-arguments result and input schemas publish `additionalProperties: false`. HTTP cannot be strict natively: `HttpApi.ParseOptions` also governs error encoding, where `onExcessProperty: "error"` rejects an error's own `stack`.
 
 ## Failure modes
 

package/docs/ActionGroup.md

@@ -124,11 +124,11 @@ export const MathApp = MathActions.implement({ double: ({ value }) => Effect.suc
 
 - Without a policy, HTTP answers decoding and encoding failures with Effect's native empty 400.
 - With a policy, `map` receives the native `HttpApiSchemaError` (`kind`, `cause`) and returns one of `errors`. HTTP uses that error's `httpApiStatus`, and the error appears in `Http.api`, in clients, and in OpenAPI.
-- `kind` values: `Payload` (input decoding), `Body` (success encoding), plus `Parameters`, `RequestHeaders`, `Query`, `ResponseHeaders`.
+- `kind` values: `Payload` (input decoding) and `Body` (success encoding). Actions declare no parameters, query, or headers, so no other kind occurs.
 - MCP is unaffected. The native `McpServer` answers invalid arguments and unencodable results itself.
 - Policy errors extend the transport contract, not the handler contract. A handler cannot return them.
 - The policy runs only on the server. Client-side codec failures stay `SchemaError`.
-- `cause` may contain input values. Never reflect it into the response.
+- HTTP decodes with `errors: "all"`, so `cause` carries every issue. Issues never retain the rejected values.
 - Groups served by one adapter may have different policies; each action answers with its own group's.
 - Domain errors, defects, interruptions, and protocol errors are not remapped. An unencodable declared error is a defect. A broken policy error is not recursively remapped.
 

package/docs/ActionMcp.md

@@ -118,6 +118,7 @@ Layer.launch(layer).pipe(
 - Defects and encoding failures produce the generic `isError` text `Tool execution failed due to an internal server error.`; the cause is logged, not sent.
 - Tool discovery is not filtered by actor. Every caller sees every tool of the endpoint. Authorization happens in the handler.
 - Cancellation is Effect's native RPC interruption.
+- Handlers may yield `McpSchema.McpRequestContext` for the client's declared information; the native server supplies it to every tool call, so it is never a router or host requirement.
 - stdio: the host supplies `Stdio` (`NodeStdio.layer`) and any request-time services explicitly, including the trusted principal. There is no authentication middleware. Tool arguments never establish identity. Keep stdout for protocol messages only and route logs to stderr.
 - Each endpoint or subprocess owns a fresh native tool registry. That isolates tool names, not application context.
 

package/docs/guarantees.md

@@ -27,7 +27,7 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 
 - A group `schemaError` policy replaces the empty 400s on HTTP with a declared error and status. It never affects MCP. Details in [ActionGroup.md](ActionGroup.md).
 - Routes are `POST <apiPath>/<group>/<action>`. Operation IDs are `<group>.<action>`. Effect generates OpenAPI component names and references.
-- Object schemas strip excess fields unless configured to reject them.
+- HTTP strips undeclared input fields. MCP tools are strict (`Tool.Strict`): undeclared arguments are an invalid-arguments result and input schemas publish `additionalProperties: false`. HTTP cannot be strict natively: `HttpApi.ParseOptions` also governs error encoding, where `onExcessProperty: "error"` rejects an error's own `stack`.
 
 ## Namespaces
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/effect-actions",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Define Effect action contracts once and project them onto HTTP, MCP, native Toolkits, catalogs, and CLIs.",
   "homepage": "https://github.com/gjermundgaraba/effect-actions#readme",
   "bugs": {