apps 1.0.0-beta.3 → 1.0.0-beta.4

package/dist/authoring/index.d.ts

@@ -102,6 +102,7 @@ export interface RequirementSpec {
     readonly description?: string;
 }
 declare const RequirementKey: unique symbol;
+declare const ServiceDeclKey: unique symbol;
 declare const RequirementPhantom: unique symbol;
 /** Requirement arity, tracked at the type level so handler contexts
  * know whether a role arrives as one entry, maybe-one, or a list. */
@@ -111,8 +112,8 @@ export type RequirementArity = "one" | "optional" | "many";
  * a requirement (bare value = arity "one"); .optional()/.array()
  * return terminal Requirements so nonsense chains do not typecheck.
  * The phantom property is never assigned — it exists so auth-compose
- * callbacks and handler contexts can recover the service's grants, a
- * .grant() pin, and the arity at the type level.
+ * callbacks and handler contexts can recover the service's grants, an
+ * auth-door pin, and the arity at the type level.
  */
 export interface Requirement<D extends ServiceDecl = ServiceDecl, G extends string | undefined = string | undefined, A extends RequirementArity = RequirementArity> {
     readonly [RequirementKey]: RequirementSpec;
@@ -123,13 +124,33 @@ export interface Requirement<D extends ServiceDecl = ServiceDecl, G extends stri
     };
     describe(text: string): Requirement<D, G, A>;
 }
-export interface Service<D extends ServiceDecl = ServiceDecl, G extends (keyof NonNullable<D["auth"]> & string) | undefined = undefined> extends Requirement<D, G, "one"> {
-    readonly decl: D;
-    optional(): Requirement<D, G, "optional">;
-    array(): Requirement<D, G, "many">;
-    /** Pin one auth method: this tool supports only the named grant. */
-    grant<N extends keyof NonNullable<D["auth"]> & string>(name: N): Service<D, N>;
-    describe(text: string): Service<D, G>;
+/**
+ * A grant-pinned requirement: what `service.auth.<name>` returns. A
+ * deliberately narrower type than Service — it can shape arity and
+ * describe itself, but carries no `auth` (pinning twice is nonsense)
+ * and no declaration access. Pinning is property access because the
+ * grants are static facts of the declaration: `github.auth.pat`
+ * autocompletes and a wrong name fails compilation.
+ */
+export interface PinnedRequirement<D extends ServiceDecl = ServiceDecl, N extends string = string> extends Requirement<D, N, "one"> {
+    optional(): Requirement<D, N, "optional">;
+    array(): Requirement<D, N, "many">;
+    describe(text: string): PinnedRequirement<D, N>;
+}
+/** The grant-pinned doors of a service, keyed by declared auth method. */
+export type ServiceAuth<D extends ServiceDecl> = {
+    readonly [N in keyof NonNullable<D["auth"]> & string]: PinnedRequirement<D, N>;
+};
+export interface Service<D extends ServiceDecl = ServiceDecl> extends Requirement<D, undefined, "one"> {
+    /** Symbol-keyed so author IntelliSense shows only authoring verbs;
+     * the declaration is plumbing the manifest reads at collection. */
+    readonly [ServiceDeclKey]: D;
+    /** Pin one auth method: `github.auth.pat` is this tool supporting
+     * only that grant. */
+    readonly auth: ServiceAuth<D>;
+    optional(): Requirement<D, undefined, "optional">;
+    array(): Requirement<D, undefined, "many">;
+    describe(text: string): Service<D>;
 }
 /** A publish-time authoring problem accumulated without interrupting defines. */
 export interface Problem {
@@ -223,11 +244,17 @@ export interface DiscoveredToolSpec {
 export interface DynamicToolsDecl<Reqs extends Readonly<Record<string, Requirement>> | undefined = Readonly<Record<string, Requirement>> | undefined> {
     readonly description: string;
     readonly requirements?: Reqs;
-    discover(ctx: HandlerCtx<Reqs>): Promise<readonly DiscoveredToolSpec[]>;
-    call(tool: {
-        readonly name: string;
-        readonly detail: unknown;
-    }, input: unknown, ctx: HandlerCtx<Reqs>): Promise<unknown>;
+    discover(args: {
+        readonly ctx: HandlerCtx<Reqs>;
+    }): Promise<readonly DiscoveredToolSpec[]>;
+    call(args: {
+        readonly tool: {
+            readonly name: string;
+            readonly detail: unknown;
+        };
+        readonly input: unknown;
+        readonly ctx: HandlerCtx<Reqs>;
+    }): Promise<unknown>;
 }
 /**
  * The erased registry row of a dynamic pair — same storage boundary
@@ -240,11 +267,8 @@ export interface DynamicToolsDecl<Reqs extends Readonly<Record<string, Requireme
 export interface DynamicToolsSpec {
     readonly description: string;
     readonly requirements?: Readonly<Record<string, Requirement>>;
-    discover(ctx: never): Promise<readonly DiscoveredToolSpec[]>;
-    call(tool: {
-        readonly name: string;
-        readonly detail: unknown;
-    }, input: never, ctx: never): Promise<unknown>;
+    discover(args: never): Promise<readonly DiscoveredToolSpec[]>;
+    call(args: never): Promise<unknown>;
 }
 declare const DynamicKey: unique symbol;
 /** The value defineDynamicTools returns: an opaque handle a tool file
@@ -330,7 +354,7 @@ export type InferSchema<S> = S extends {
 /**
  * The capability a handler receives for one connected requirement
  * role: the grant's kind-discriminated material (narrowed by any
- * .grant() pin) plus the spending fetch. Arity shapes the value —
+ * auth-door pin) plus the spending fetch. Arity shapes the value —
  * `.optional()` may be absent, `.array()` is every connected account.
  */
 export type HandlerRole<R> = R extends Requirement<infer D, infer G, infer A> ? [A] extends ["many"] ? ReadonlyArray<HandlerRoleEntry<D, G>> : [A] extends ["optional"] ? HandlerRoleEntry<D, G> | undefined : HandlerRoleEntry<D, G> : never;
@@ -354,7 +378,9 @@ export interface ToolAnnotations {
  * The generic authored shape: input/ctx/output are all inferred — the
  * handler's input from the Standard Schema, ctx from the requirements
  * record (grants, pins, arity), and the return type checked against
- * the output schema when one is stated.
+ * the output schema when one is stated. The handler takes ONE
+ * destructurable argument so unused halves never demand an underscore:
+ * `handler: async ({ input }) => ...` / `async ({ ctx }) => ...`.
  */
 export interface ToolDecl<Input extends SchemaLike = SchemaLike, Reqs extends Readonly<Record<string, Requirement>> | undefined = Readonly<Record<string, Requirement>> | undefined, Output extends SchemaLike | undefined = SchemaLike | undefined> {
     /** Address segment. Single-tool files may omit it (filename). */
@@ -364,7 +390,10 @@ export interface ToolDecl<Input extends SchemaLike = SchemaLike, Reqs extends Re
     readonly input: Input;
     readonly output?: Output;
     readonly annotations?: ToolAnnotations;
-    handler(input: InferSchema<Input>, ctx: HandlerCtx<Reqs>): Promise<Output extends SchemaLike ? InferSchema<Output> : unknown>;
+    handler(args: {
+        readonly input: InferSchema<Input>;
+        readonly ctx: HandlerCtx<Reqs>;
+    }): Promise<Output extends SchemaLike ? InferSchema<Output> : unknown>;
 }
 /**
  * The erased registry row. Registration drops the generics — storage
@@ -380,7 +409,7 @@ export interface ToolSpec {
     readonly input: SchemaLike;
     readonly output?: SchemaLike;
     readonly annotations?: ToolAnnotations;
-    handler(input: never, ctx: never): Promise<unknown>;
+    handler(args: never): Promise<unknown>;
 }
 declare const ToolKey: unique symbol;
 export interface Tool {

package/dist/authoring/index.js

@@ -15,7 +15,7 @@ import {
   service,
   setActiveRegistry,
   toolSpecOf
-} from "../chunk-A3H32P2J.js";
+} from "../chunk-535V5K64.js";
 export {
   __enterFile,
   __leaveFile,

package/dist/{chunk-MUFMJRXR.js → chunk-2DVKSPQH.js}

@@ -232,7 +232,7 @@ var callTool = async (registry, address, input, ctx, detail) => {
     if (!parsed2.ok) return failure("input", parsed2.reason);
     try {
       const handler = registered.spec.handler;
-      return { ok: true, value: await handler(parsed2.value, ctx) };
+      return { ok: true, value: await handler({ input: parsed2.value, ctx }) };
     } catch (error) {
       return failure("handler", `handler failed (${errorMessage(error)})`);
     }
@@ -254,7 +254,11 @@ var callTool = async (registry, address, input, ctx, detail) => {
     const call = pair.call;
     return {
       ok: true,
-      value: await call({ name: dynamic.name, detail }, parsed.value, ctx)
+      value: await call({
+        tool: { name: dynamic.name, detail },
+        input: parsed.value,
+        ctx
+      })
     };
   } catch (error) {
     return failure("handler", `dynamic call failed (${errorMessage(error)})`);
@@ -268,7 +272,7 @@ var discoverTool = async (registry, segment, ctx) => {
   let emitted;
   try {
     const discover = pair.discover;
-    emitted = await discover(ctx);
+    emitted = await discover({ ctx });
   } catch (error) {
     return { ok: false, reason: `discover failed (${errorMessage(error)})` };
   }

package/dist/{chunk-A3H32P2J.js → chunk-535V5K64.js}

@@ -4,6 +4,7 @@ var basic = (opts) => ({ kind: "basic", ...opts });
 var secrets = (opts) => ({ kind: "secrets", ...opts });
 var oauth = (opts) => ({ kind: "oauth", ...opts });
 var RequirementKey = Symbol.for("executor/apps/requirement");
+var ServiceDeclKey = Symbol.for("executor/apps/service-decl");
 var recordAuthoringProblem = (message) => {
   const file = sourceFileFor("wrapper");
   activeRegistry.problems.push({ message: `${file}: ${message}` });
@@ -73,12 +74,23 @@ var makeTerminal = (spec) => ({
 });
 var service = (decl) => {
   const file = sourceFileFor("service(...)");
+  const makePinned = (spec) => ({
+    [RequirementKey]: spec,
+    optional: () => makeTerminal({ ...spec, arity: "optional" }),
+    array: () => makeTerminal({ ...spec, arity: "many" }),
+    describe: (text) => makePinned({ ...spec, description: text })
+  });
   const make = (spec) => ({
     [RequirementKey]: spec,
-    decl,
+    [ServiceDeclKey]: decl,
+    auth: Object.fromEntries(
+      Object.keys(decl.auth ?? {}).map((name) => [
+        name,
+        makePinned({ ...spec, grant: name })
+      ])
+    ),
     optional: () => makeTerminal({ ...spec, arity: "optional" }),
     array: () => makeTerminal({ ...spec, arity: "many" }),
-    grant: (name) => make({ ...spec, grant: name }),
     describe: (text) => make({ ...spec, description: text })
   });
   const value = make({ service: decl, arity: "one" });
@@ -87,7 +99,7 @@ var service = (decl) => {
   return value;
 };
 var isRequirement = (value) => typeof value === "object" && value !== null && RequirementKey in value;
-var isService = (value) => isRequirement(value) && "decl" in value && "optional" in value && "array" in value && "grant" in value;
+var isService = (value) => isRequirement(value) && ServiceDeclKey in value;
 var requirementSpecOf = (value) => isService(value) || isRequirement(value) ? value[RequirementKey] : void 0;
 var defineApp = (manifest) => {
   const file = sourceFileFor("defineApp(...)");

package/dist/{chunk-YUZ4TXOY.js → chunk-DP6UJCMX.js}

@@ -1,6 +1,6 @@
 import {
   defineDynamicTools
-} from "./chunk-A3H32P2J.js";
+} from "./chunk-535V5K64.js";
 
 // src/mcp/client.ts
 var mcpDiscover = async (_endpoint, _ctx, _auth, _operations) => {
@@ -17,8 +17,8 @@ function fromMCP(endpoint, options) {
   return defineDynamicTools({
     description: `Tools served by the MCP server at ${endpoint}.`,
     ...options?.requirements === void 0 ? {} : { requirements: options.requirements },
-    discover: (ctx) => mcpDiscover(endpoint, ctx, auth, operations),
-    call: (tool, input, ctx) => mcpCall(endpoint, tool.name, input, ctx, auth)
+    discover: ({ ctx }) => mcpDiscover(endpoint, ctx, auth, operations),
+    call: ({ tool, input, ctx }) => mcpCall(endpoint, tool.name, input, ctx, auth)
   });
 }
 

package/dist/{chunk-F7GZYEAC.js → chunk-QA72XJZU.js}

@@ -2,7 +2,7 @@ import {
   defineDynamicTools,
   recordAuthoringProblem,
   requirementSpecOf
-} from "./chunk-A3H32P2J.js";
+} from "./chunk-535V5K64.js";
 
 // src/openapi/mapper.ts
 var openapiDiscover = async (_spec, _ctx, _auth, _operations) => {
@@ -31,8 +31,8 @@ function fromOpenAPI(spec, options) {
   return defineDynamicTools({
     description: typeof spec === "string" && spec.startsWith("https://") ? `Operations from the OpenAPI document at ${spec}.` : "Operations from an OpenAPI document shipped with the app.",
     ...options?.requirements === void 0 ? {} : { requirements: options.requirements },
-    discover: (ctx) => openapiDiscover(spec, ctx, auth, operations),
-    call: (tool, input, ctx) => openapiCall(tool, input, ctx, auth)
+    discover: ({ ctx }) => openapiDiscover(spec, ctx, auth, operations),
+    call: ({ tool, input, ctx }) => openapiCall(tool, input, ctx, auth)
   });
 }
 

package/dist/{chunk-Y6LLTN7W.js → chunk-XYT6GZ7M.js}

@@ -1,6 +1,6 @@
 import {
   manifestOf
-} from "./chunk-MUFMJRXR.js";
+} from "./chunk-2DVKSPQH.js";
 import {
   PublishError
 } from "./chunk-B7NEUIJL.js";
@@ -9,7 +9,7 @@ import {
   __leaveFile,
   newRegistry,
   setActiveRegistry
-} from "./chunk-A3H32P2J.js";
+} from "./chunk-535V5K64.js";
 
 // src/manifest/index.ts
 import { fileURLToPath, pathToFileURL } from "node:url";

package/dist/index.js

@@ -1,12 +1,12 @@
 import {
   fromOpenAPI
-} from "./chunk-F7GZYEAC.js";
+} from "./chunk-QA72XJZU.js";
 import {
   authHeaders
 } from "./chunk-S5KFP4JQ.js";
 import {
   fromMCP
-} from "./chunk-YUZ4TXOY.js";
+} from "./chunk-DP6UJCMX.js";
 import {
   __enterFile,
   __leaveFile,
@@ -24,7 +24,7 @@ import {
   service,
   setActiveRegistry,
   toolSpecOf
-} from "./chunk-A3H32P2J.js";
+} from "./chunk-535V5K64.js";
 export {
   __enterFile,
   __leaveFile,

package/dist/manifest/index.js

@@ -1,13 +1,13 @@
 import {
   loadApp,
   manifest
-} from "../chunk-Y6LLTN7W.js";
-import "../chunk-MUFMJRXR.js";
+} from "../chunk-XYT6GZ7M.js";
+import "../chunk-2DVKSPQH.js";
 import {
   JsonSchemaObject,
   PublishError
 } from "../chunk-B7NEUIJL.js";
-import "../chunk-A3H32P2J.js";
+import "../chunk-535V5K64.js";
 export {
   JsonSchemaObject,
   PublishError,

package/dist/mcp/index.js

@@ -1,7 +1,7 @@
 import {
   fromMCP
-} from "../chunk-YUZ4TXOY.js";
-import "../chunk-A3H32P2J.js";
+} from "../chunk-DP6UJCMX.js";
+import "../chunk-535V5K64.js";
 export {
   fromMCP
 };

package/dist/openapi/index.js

@@ -1,7 +1,7 @@
 import {
   fromOpenAPI
-} from "../chunk-F7GZYEAC.js";
-import "../chunk-A3H32P2J.js";
+} from "../chunk-QA72XJZU.js";
+import "../chunk-535V5K64.js";
 export {
   fromOpenAPI
 };

package/dist/runner/index.js

@@ -1,16 +1,16 @@
 import {
   loadApp
-} from "../chunk-Y6LLTN7W.js";
+} from "../chunk-XYT6GZ7M.js";
 import {
   callTool,
   discoverTool
-} from "../chunk-MUFMJRXR.js";
+} from "../chunk-2DVKSPQH.js";
 import "../chunk-B7NEUIJL.js";
 import {
   CallError,
   DiscoverError
 } from "../chunk-4OZFMCTT.js";
-import "../chunk-A3H32P2J.js";
+import "../chunk-535V5K64.js";
 
 // src/runner/index.ts
 import { Effect } from "effect";

package/dist/runtime/index.js

@@ -3,7 +3,7 @@ import {
   compileInputSchema,
   discoverTool,
   manifestOf
-} from "../chunk-MUFMJRXR.js";
+} from "../chunk-2DVKSPQH.js";
 export {
   callTool,
   compileInputSchema,

package/dist/workerd/index.js

@@ -2,7 +2,7 @@ import {
   callTool,
   discoverTool,
   manifestOf
-} from "../chunk-MUFMJRXR.js";
+} from "../chunk-2DVKSPQH.js";
 export {
   callTool,
   discoverTool,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apps",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.4",
   "description": "Author executor apps: declare services, auth, and tools in plain TypeScript; the executor platform runs, validates, and serves them.",
   "license": "MIT",
   "type": "module",

package/src/authoring/index.ts

@@ -126,6 +126,7 @@ export interface RequirementSpec {
 }
 
 const RequirementKey: unique symbol = Symbol.for("executor/apps/requirement");
+const ServiceDeclKey: unique symbol = Symbol.for("executor/apps/service-decl");
 
 declare const RequirementPhantom: unique symbol;
 
@@ -138,8 +139,8 @@ export type RequirementArity = "one" | "optional" | "many";
  * a requirement (bare value = arity "one"); .optional()/.array()
  * return terminal Requirements so nonsense chains do not typecheck.
  * The phantom property is never assigned — it exists so auth-compose
- * callbacks and handler contexts can recover the service's grants, a
- * .grant() pin, and the arity at the type level.
+ * callbacks and handler contexts can recover the service's grants, an
+ * auth-door pin, and the arity at the type level.
  */
 export interface Requirement<
   D extends ServiceDecl = ServiceDecl,
@@ -155,16 +156,39 @@ export interface Requirement<
   describe(text: string): Requirement<D, G, A>;
 }
 
-export interface Service<
+/**
+ * A grant-pinned requirement: what `service.auth.<name>` returns. A
+ * deliberately narrower type than Service — it can shape arity and
+ * describe itself, but carries no `auth` (pinning twice is nonsense)
+ * and no declaration access. Pinning is property access because the
+ * grants are static facts of the declaration: `github.auth.pat`
+ * autocompletes and a wrong name fails compilation.
+ */
+export interface PinnedRequirement<
   D extends ServiceDecl = ServiceDecl,
-  G extends (keyof NonNullable<D["auth"]> & string) | undefined = undefined,
-> extends Requirement<D, G, "one"> {
-  readonly decl: D;
-  optional(): Requirement<D, G, "optional">;
-  array(): Requirement<D, G, "many">;
-  /** Pin one auth method: this tool supports only the named grant. */
-  grant<N extends keyof NonNullable<D["auth"]> & string>(name: N): Service<D, N>;
-  describe(text: string): Service<D, G>;
+  N extends string = string,
+> extends Requirement<D, N, "one"> {
+  optional(): Requirement<D, N, "optional">;
+  array(): Requirement<D, N, "many">;
+  describe(text: string): PinnedRequirement<D, N>;
+}
+
+/** The grant-pinned doors of a service, keyed by declared auth method. */
+export type ServiceAuth<D extends ServiceDecl> = {
+  readonly [N in keyof NonNullable<D["auth"]> & string]: PinnedRequirement<D, N>;
+};
+
+export interface Service<D extends ServiceDecl = ServiceDecl>
+  extends Requirement<D, undefined, "one"> {
+  /** Symbol-keyed so author IntelliSense shows only authoring verbs;
+   * the declaration is plumbing the manifest reads at collection. */
+  readonly [ServiceDeclKey]: D;
+  /** Pin one auth method: `github.auth.pat` is this tool supporting
+   * only that grant. */
+  readonly auth: ServiceAuth<D>;
+  optional(): Requirement<D, undefined, "optional">;
+  array(): Requirement<D, undefined, "many">;
+  describe(text: string): Service<D>;
 }
 
 /** A publish-time authoring problem accumulated without interrupting defines. */
@@ -294,12 +318,12 @@ export interface DynamicToolsDecl<
 > {
   readonly description: string;
   readonly requirements?: Reqs;
-  discover(ctx: HandlerCtx<Reqs>): Promise<readonly DiscoveredToolSpec[]>;
-  call(
-    tool: { readonly name: string; readonly detail: unknown },
-    input: unknown,
-    ctx: HandlerCtx<Reqs>,
-  ): Promise<unknown>;
+  discover(args: { readonly ctx: HandlerCtx<Reqs> }): Promise<readonly DiscoveredToolSpec[]>;
+  call(args: {
+    readonly tool: { readonly name: string; readonly detail: unknown };
+    readonly input: unknown;
+    readonly ctx: HandlerCtx<Reqs>;
+  }): Promise<unknown>;
 }
 
 /**
@@ -313,12 +337,8 @@ export interface DynamicToolsDecl<
 export interface DynamicToolsSpec {
   readonly description: string;
   readonly requirements?: Readonly<Record<string, Requirement>>;
-  discover(ctx: never): Promise<readonly DiscoveredToolSpec[]>;
-  call(
-    tool: { readonly name: string; readonly detail: unknown },
-    input: never,
-    ctx: never,
-  ): Promise<unknown>;
+  discover(args: never): Promise<readonly DiscoveredToolSpec[]>;
+  call(args: never): Promise<unknown>;
 }
 
 const DynamicKey: unique symbol = Symbol.for("executor/apps/dynamic");
@@ -462,18 +482,28 @@ const makeTerminal = <
 
 export const service = <const D extends ServiceDecl>(decl: D): Service<D> => {
   const file = sourceFileFor("service(...)");
-  const make = <G extends (keyof NonNullable<D["auth"]> & string) | undefined>(
+  const makePinned = <N extends keyof NonNullable<D["auth"]> & string>(
     spec: RequirementSpec,
-  ): Service<D, G> => ({
+  ): PinnedRequirement<D, N> => ({
+    [RequirementKey]: spec,
+    optional: () => makeTerminal<D, N, "optional">({ ...spec, arity: "optional" }),
+    array: () => makeTerminal<D, N, "many">({ ...spec, arity: "many" }),
+    describe: (text) => makePinned<N>({ ...spec, description: text }),
+  });
+  const make = (spec: RequirementSpec): Service<D> => ({
     [RequirementKey]: spec,
-    decl,
-    optional: () => makeTerminal<D, G, "optional">({ ...spec, arity: "optional" }),
-    array: () => makeTerminal<D, G, "many">({ ...spec, arity: "many" }),
-    grant: <N extends keyof NonNullable<D["auth"]> & string>(name: N) =>
-      make<N>({ ...spec, grant: name }),
-    describe: (text) => make<G>({ ...spec, description: text }),
+    [ServiceDeclKey]: decl,
+    auth: Object.fromEntries(
+      Object.keys(decl.auth ?? {}).map((name) => [
+        name,
+        makePinned({ ...spec, grant: name }),
+      ]),
+    ) as ServiceAuth<D>,
+    optional: () => makeTerminal<D, undefined, "optional">({ ...spec, arity: "optional" }),
+    array: () => makeTerminal<D, undefined, "many">({ ...spec, arity: "many" }),
+    describe: (text) => make({ ...spec, description: text }),
   });
-  const value = make<undefined>({ service: decl, arity: "one" });
+  const value = make({ service: decl, arity: "one" });
   if (!activeRegistry.services.has(decl.origin))
     activeRegistry.services.set(decl.origin, { decl, file });
   return value;
@@ -483,11 +513,7 @@ const isRequirement = (value: unknown): value is Requirement =>
   typeof value === "object" && value !== null && RequirementKey in value;
 
 const isService = (value: unknown): value is Service =>
-  isRequirement(value) &&
-  "decl" in value &&
-  "optional" in value &&
-  "array" in value &&
-  "grant" in value;
+  isRequirement(value) && ServiceDeclKey in value;
 
 export const requirementSpecOf = (value: unknown): RequirementSpec | undefined =>
   isService(value) || isRequirement(value) ? value[RequirementKey] : undefined;
@@ -535,7 +561,7 @@ export type InferSchema<S> = S extends {
 /**
  * The capability a handler receives for one connected requirement
  * role: the grant's kind-discriminated material (narrowed by any
- * .grant() pin) plus the spending fetch. Arity shapes the value —
+ * auth-door pin) plus the spending fetch. Arity shapes the value —
  * `.optional()` may be absent, `.array()` is every connected account.
  */
 export type HandlerRole<R> = R extends Requirement<infer D, infer G, infer A>
@@ -570,7 +596,9 @@ export interface ToolAnnotations {
  * The generic authored shape: input/ctx/output are all inferred — the
  * handler's input from the Standard Schema, ctx from the requirements
  * record (grants, pins, arity), and the return type checked against
- * the output schema when one is stated.
+ * the output schema when one is stated. The handler takes ONE
+ * destructurable argument so unused halves never demand an underscore:
+ * `handler: async ({ input }) => ...` / `async ({ ctx }) => ...`.
  */
 export interface ToolDecl<
   Input extends SchemaLike = SchemaLike,
@@ -586,10 +614,10 @@ export interface ToolDecl<
   readonly input: Input;
   readonly output?: Output;
   readonly annotations?: ToolAnnotations;
-  handler(
-    input: InferSchema<Input>,
-    ctx: HandlerCtx<Reqs>,
-  ): Promise<Output extends SchemaLike ? InferSchema<Output> : unknown>;
+  handler(args: {
+    readonly input: InferSchema<Input>;
+    readonly ctx: HandlerCtx<Reqs>;
+  }): Promise<Output extends SchemaLike ? InferSchema<Output> : unknown>;
 }
 
 /**
@@ -606,7 +634,7 @@ export interface ToolSpec {
   readonly input: SchemaLike;
   readonly output?: SchemaLike;
   readonly annotations?: ToolAnnotations;
-  handler(input: never, ctx: never): Promise<unknown>;
+  handler(args: never): Promise<unknown>;
 }
 
 const ToolKey: unique symbol = Symbol.for("executor/apps/tool");

package/src/mcp/index.ts

@@ -36,7 +36,7 @@ export function fromMCP(
   return defineDynamicTools({
     description: `Tools served by the MCP server at ${endpoint}.`,
     ...(options?.requirements === undefined ? {} : { requirements: options.requirements }),
-    discover: (ctx) => mcpDiscover(endpoint, ctx, auth, operations),
-    call: (tool, input, ctx) => mcpCall(endpoint, tool.name, input, ctx, auth),
+    discover: ({ ctx }) => mcpDiscover(endpoint, ctx, auth, operations),
+    call: ({ tool, input, ctx }) => mcpCall(endpoint, tool.name, input, ctx, auth),
   });
 }

package/src/openapi/index.ts

@@ -64,7 +64,7 @@ export function fromOpenAPI(
         ? `Operations from the OpenAPI document at ${spec}.`
         : "Operations from an OpenAPI document shipped with the app.",
     ...(options?.requirements === undefined ? {} : { requirements: options.requirements }),
-    discover: (ctx) => openapiDiscover(spec, ctx, auth, operations),
-    call: (tool, input, ctx) => openapiCall(tool, input, ctx, auth),
+    discover: ({ ctx }) => openapiDiscover(spec, ctx, auth, operations),
+    call: ({ tool, input, ctx }) => openapiCall(tool, input, ctx, auth),
   });
 }

package/src/runtime/index.ts

@@ -457,11 +457,11 @@ export const callTool = async (
     try {
       // SAFETY: ToolSpec intentionally erases authored handler inputs to keep
       // authoring generic-free; validation and ToolCtx establish this call boundary.
-      const handler = registered.spec.handler as (
-        value: unknown,
-        toolCtx: ToolCtx,
-      ) => Promise<unknown>;
-      return { ok: true, value: await handler(parsed.value, ctx) };
+      const handler = registered.spec.handler as (args: {
+        readonly input: unknown;
+        readonly ctx: ToolCtx;
+      }) => Promise<unknown>;
+      return { ok: true, value: await handler({ input: parsed.value, ctx }) };
     } catch (error) {
       return failure("handler", `handler failed (${errorMessage(error)})`);
     }
@@ -481,14 +481,18 @@ export const callTool = async (
   const parsed = await parseInput(discovered.input, input);
   if (!parsed.ok) return failure("input", parsed.reason);
   try {
-    const call = pair.call as (
-      tool: { readonly name: string; readonly detail: unknown },
-      value: unknown,
-      toolCtx: ToolCtx,
-    ) => Promise<unknown>;
+    const call = pair.call as (args: {
+      readonly tool: { readonly name: string; readonly detail: unknown };
+      readonly input: unknown;
+      readonly ctx: ToolCtx;
+    }) => Promise<unknown>;
     return {
       ok: true,
-      value: await call({ name: dynamic.name, detail }, parsed.value, ctx),
+      value: await call({
+        tool: { name: dynamic.name, detail },
+        input: parsed.value,
+        ctx,
+      }),
     };
   } catch (error) {
     return failure("handler", `dynamic call failed (${errorMessage(error)})`);
@@ -508,10 +512,10 @@ export const discoverTool = async (
 
   let emitted: readonly DiscoveredToolSpec[];
   try {
-    const discover = pair.discover as (
-      toolCtx: ToolCtx,
-    ) => Promise<readonly DiscoveredToolSpec[]>;
-    emitted = await discover(ctx);
+    const discover = pair.discover as (args: {
+      readonly ctx: ToolCtx;
+    }) => Promise<readonly DiscoveredToolSpec[]>;
+    emitted = await discover({ ctx });
   } catch (error) {
     return { ok: false, reason: `discover failed (${errorMessage(error)})` };
   }