apps 1.0.0-beta.2 → 1.0.0-beta.3

package/dist/authoring/index.d.ts

@@ -3,6 +3,18 @@
  * Authored modules record plain claims without I/O or user context; the
  * manifest loader owns execution, validation, and effects.
  */
+/** A single opaque credential with RFC 6750 bearer semantics. */
+export interface BearerMethod {
+    readonly kind: "bearer";
+    readonly label: string;
+    readonly help?: string;
+}
+/** An RFC 7617 username/password pair. */
+export interface BasicMethod {
+    readonly kind: "basic";
+    readonly label: string;
+    readonly help?: string;
+}
 export interface SecretsMethod<F extends Readonly<Record<string, SecretField>> = Readonly<Record<string, SecretField>>> {
     readonly kind: "secrets";
     readonly label: string;
@@ -17,7 +29,7 @@ export interface SecretField {
     readonly secret: boolean;
 }
 /**
- * An oauth auth method is a secrets-shaped auth method with acquisition strategies
+ * An oauth auth method is a bearer method with acquisition strategies
  * layered on: the material contract is always {token, refresh_token?,
  * expires_at?}, and the host fills it by the best strategy it can offer
  * — authorization-code ceremony, device-code ceremony, or paste. Paste
@@ -41,7 +53,15 @@ export interface OAuthMethod {
      * (audience-bound tokens, DPoP). Stated, never inferred. */
     readonly paste?: false;
 }
-export type AuthMethod = SecretsMethod | OAuthMethod;
+export type AuthMethod = BearerMethod | BasicMethod | SecretsMethod | OAuthMethod;
+export declare const bearer: (opts: {
+    readonly label: string;
+    readonly help?: string;
+}) => BearerMethod;
+export declare const basic: (opts: {
+    readonly label: string;
+    readonly help?: string;
+}) => BasicMethod;
 export declare const secrets: <const F extends Readonly<Record<string, SecretField>>>(opts: {
     readonly label: string;
     /** Markdown shown under this auth method on the connect page, for example:
@@ -82,55 +102,171 @@ export interface RequirementSpec {
     readonly description?: string;
 }
 declare const RequirementKey: 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. */
+export type RequirementArity = "one" | "optional" | "many";
 /**
  * A requirement value in a tool's `requirements` record. A Service IS
  * 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.
  */
-export interface Requirement<D extends ServiceDecl = ServiceDecl> {
+export interface Requirement<D extends ServiceDecl = ServiceDecl, G extends string | undefined = string | undefined, A extends RequirementArity = RequirementArity> {
     readonly [RequirementKey]: RequirementSpec;
-    describe(text: string): Requirement<D>;
+    readonly [RequirementPhantom]?: {
+        readonly decl: D;
+        readonly pinned: G;
+        readonly arity: A;
+    };
+    describe(text: string): Requirement<D, G, A>;
 }
-export interface Service<D extends ServiceDecl = ServiceDecl> extends Requirement<D> {
+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>;
-    array(): Requirement<D>;
+    optional(): Requirement<D, G, "optional">;
+    array(): Requirement<D, G, "many">;
     /** Pin one auth method: this tool supports only the named grant. */
-    grant(name: keyof NonNullable<D["auth"]> & string): Service<D>;
-    describe(text: string): Service<D>;
+    grant<N extends keyof NonNullable<D["auth"]> & string>(name: N): Service<D, N>;
+    describe(text: string): Service<D, G>;
 }
 /** A publish-time authoring problem accumulated without interrupting defines. */
 export interface Problem {
     readonly message: string;
 }
-/**
- * A dynamic tool-set claim: tools discovered from a live surface (an
- * MCP server's tool list, an OpenAPI document) rather than authored one
- * file at a time. The claim is recorded at publish time; discovery runs
- * later, per connection — an app with zero static tools and one claim
- * saves green, and listing never blocks on an upstream.
- */
-export type DynamicClaimSpec = {
-    readonly kind: "mcp";
-    readonly requirement: RequirementSpec;
-    /** MCP endpoint URL. Absent = the service origin at its root path. */
-    readonly endpoint?: string;
+/** One connected role, discriminated by the declared auth method kind. */
+export type AuthRoleEntry<D extends ServiceDecl> = {
+    [N in keyof NonNullable<D["auth"]> & string]: NonNullable<D["auth"]>[N] extends SecretsMethod<infer F> ? {
+        readonly grant: N;
+        readonly kind: "secrets";
+        readonly secrets: {
+            readonly [K in keyof F & string]: string;
+        };
+    } : NonNullable<D["auth"]>[N] extends BasicMethod ? {
+        readonly grant: N;
+        readonly kind: "basic";
+        readonly username: string;
+        readonly password: string;
+    } : {
+        readonly grant: N;
+        readonly kind: "bearer" | "oauth";
+        readonly token: string;
+    };
+}[keyof NonNullable<D["auth"]> & string];
+/** Kind-discriminated credential material accepted by surface helpers. */
+export type RoleMaterial = {
+    readonly kind: "bearer" | "oauth";
+    readonly token: string;
 } | {
-    readonly kind: "openapi";
-    readonly requirement: RequirementSpec;
-    /** OpenAPI document: an absolute URL or an app-relative path. */
-    readonly spec: string;
+    readonly kind: "basic";
+    readonly username: string;
+    readonly password: string;
+} | {
+    readonly kind: "secrets";
+    readonly secrets: Readonly<Record<string, string>>;
+};
+/** Recover the connected role type produced by a service requirement. */
+export type RoleOf<S, G extends string | undefined = undefined> = S extends Requirement<infer D, infer Pin> ? [G] extends [string] ? Extract<AuthRoleEntry<D>, {
+    grant: G;
+}> : Pin extends string ? Extract<AuthRoleEntry<D>, {
+    grant: Pin;
+}> : AuthRoleEntry<D> : never;
+/** Role record received by an authored authentication placement callback. */
+export type AuthRoles<Reqs extends Readonly<Record<string, Requirement>>> = {
+    readonly [K in keyof Reqs]: NonNullable<Reqs[K][typeof RequirementPhantom]> extends {
+        readonly decl: infer D extends ServiceDecl;
+        readonly pinned: infer G;
+    } ? G extends string ? Extract<AuthRoleEntry<D>, {
+        grant: G;
+    }> : AuthRoleEntry<D> : never;
+};
+/** Request placement returned by an authored dynamic auth callback. */
+export interface AuthPlacement {
+    readonly headers?: HeadersInit;
+    readonly searchParams?: URLSearchParams | Readonly<Record<string, string>>;
+}
+export type AuthComposeFn<Reqs extends Readonly<Record<string, Requirement>> = never> = (roles: AuthRoles<Reqs>) => AuthPlacement | undefined | void;
+export type HasSecretsGrant<D extends ServiceDecl> = true extends (NonNullable<D["auth"]>[keyof NonNullable<D["auth"]>] extends infer M ? M extends SecretsMethod ? true : false : never) ? true : false;
+/** Whether an OpenAPI wrapper must state credential placement explicitly. */
+export type RequiresAuthCompose<Reqs extends Readonly<Record<string, Requirement>>> = true extends {
+    [K in keyof Reqs]: NonNullable<Reqs[K][typeof RequirementPhantom]> extends {
+        readonly decl: infer D extends ServiceDecl;
+        readonly pinned: infer G;
+    } ? G extends keyof NonNullable<D["auth"]> & string ? NonNullable<D["auth"]>[G] extends SecretsMethod ? true : false : HasSecretsGrant<D> : never;
+}[keyof Reqs] ? true : false;
+/** Record a wrapper-specific publish problem on the active authored file. @internal */
+export declare const recordAuthoringProblem: (message: string) => void;
+/** Operation curation for a dynamic tool set. Exactly one of allow/block. */
+export type OperationSelection = {
+    readonly allow: readonly string[];
+    readonly block?: undefined;
+} | {
+    readonly block: readonly string[];
+    readonly allow?: undefined;
 };
+/** One tool emitted by a dynamic discovery pass. */
+export interface DiscoveredToolSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly input: SchemaLike;
+    readonly annotations?: ToolAnnotations;
+    readonly detail?: unknown;
+}
+/**
+ * The generic authored shape of a dynamic pair: ctx is inferred from
+ * the requirements record exactly as for static tools. Discovered
+ * inputs are runtime data (the schema arrives from the upstream at
+ * discover time), so `call`'s input is honestly `unknown` — the
+ * runtime validates against the discovered descriptor before calling.
+ */
+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>;
+}
+/**
+ * The erased registry row of a dynamic pair — same storage boundary
+ * as ToolSpec. App code: runs where handlers run (in-process locally,
+ * inside the isolate on workerd) and places credentials itself from
+ * ctx, like any handler. `discover` interrogates the tool source;
+ * `call` executes one discovered tool from the identity and detail
+ * discover emitted.
+ */
+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>;
+}
 declare const DynamicKey: unique symbol;
-/** The value fromMCP/fromOpenAPI return: an opaque claim handle a tool
- * file default-exports. The spec is undefined when the claim was
+/** The value defineDynamicTools returns: an opaque handle a tool file
+ * default-exports. The spec is undefined when the definition was
  * invalid (a problem was recorded instead). */
 export interface DynamicToolSet {
-    readonly [DynamicKey]: DynamicClaimSpec | undefined;
+    readonly [DynamicKey]: DynamicToolsSpec | undefined;
 }
-/** A registered dynamic claim and its source attribution. @internal */
-export interface RegisteredDynamic {
-    readonly spec: DynamicClaimSpec;
+/** Reads a dynamic spec from a tool file's default export. @internal */
+export declare const dynamicSpecOf: (value: unknown) => DynamicToolsSpec | undefined;
+/**
+ * The dynamic-tools primitive: an author-written discover/call pair
+ * whose tool list is interrogated at runtime, per connection, instead
+ * of authored one file at a time. The file's name becomes the address
+ * segment (appKey/<stem>/<toolName>); tools land in the catalog after
+ * discovery and never block a save. fromMCP/fromOpenAPI are shipped
+ * pairs over this same primitive.
+ */
+export declare const defineDynamicTools: <const Reqs extends Readonly<Record<string, Requirement>> | undefined = undefined>(decl: DynamicToolsDecl<Reqs>) => DynamicToolSet;
+/** A registered dynamic tool set and its source attribution. @internal */
+export interface DynamicRegistration {
+    readonly spec: DynamicToolsSpec;
     readonly file: string;
 }
 /** A registered service declaration and its source attribution. @internal */
@@ -148,7 +284,7 @@ export interface Registry {
     app: AppManifest | undefined;
     readonly services: Map<string, RegisteredService>;
     readonly tools: Map<string, RegisteredTool>;
-    readonly dynamic: Map<string, RegisteredDynamic>;
+    readonly dynamic: Map<string, DynamicRegistration>;
     readonly problems: Problem[];
     readonly toolFiles: Map<string, {
         definitions: number;
@@ -178,14 +314,66 @@ export declare const defineApp: (manifest: {
 }) => AppManifest;
 /** Any Standard Schema (zod preferred) or a raw JSON-schema object. */
 export type SchemaLike = object;
+/**
+ * The validated value a Standard Schema produces, recovered from its
+ * phantom types (zod 4 and effect Schema both publish them). A raw
+ * JSON-schema object carries no phantom, so its input is `unknown` —
+ * stated weakness, not silent weakness.
+ */
+export type InferSchema<S> = S extends {
+    readonly "~standard": {
+        readonly types?: infer T;
+    };
+} ? NonNullable<T> extends {
+    readonly output: infer O;
+} ? O : unknown : unknown;
+/**
+ * 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 —
+ * `.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;
+/** One connected role entry: declared-auth material + capability fetch. */
+export type HandlerRoleEntry<D extends ServiceDecl, G extends string | undefined> = ([G] extends [string] ? Extract<AuthRoleEntry<D>, {
+    grant: G;
+}> : AuthRoleEntry<D>) & {
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+};
+/** The ctx record a handler receives, keyed by requirement role. */
+export type HandlerCtx<Reqs> = [Reqs] extends [Readonly<Record<string, Requirement>>] ? {
+    readonly [K in keyof Reqs]: HandlerRole<Reqs[K]>;
+} : Readonly<Record<never, never>>;
 export interface ToolAnnotations {
     readonly readOnly?: boolean;
     readonly destructive?: boolean;
     /** Facts, not flow: shortfall surfaces as the scope challenge. */
     readonly scopes?: readonly string[];
 }
-export interface ToolSpec {
+/**
+ * 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.
+ */
+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). */
+    readonly name?: string;
+    readonly description: string;
+    readonly requirements?: Reqs;
+    readonly input: Input;
+    readonly output?: Output;
+    readonly annotations?: ToolAnnotations;
+    handler(input: InferSchema<Input>, ctx: HandlerCtx<Reqs>): Promise<Output extends SchemaLike ? InferSchema<Output> : unknown>;
+}
+/**
+ * The erased registry row. Registration drops the generics — storage
+ * is untyped by design, the same boundary every schema library draws
+ * between its typed builders and its runtime representation. The
+ * runtime re-establishes safety by validating input before the
+ * handler runs and shaping ctx from resolved connections.
+ */
+export interface ToolSpec {
     readonly name?: string;
     readonly description: string;
     readonly requirements?: Readonly<Record<string, Requirement>>;
@@ -198,7 +386,7 @@ declare const ToolKey: unique symbol;
 export interface Tool {
     readonly [ToolKey]: ToolSpec;
 }
-export declare const defineTool: (spec: ToolSpec) => Tool;
+export declare const defineTool: <const Input extends SchemaLike, const Reqs extends Readonly<Record<string, Requirement>> | undefined = undefined, const Output extends SchemaLike | undefined = undefined>(decl: ToolDecl<Input, Reqs, Output>) => Tool;
 export declare const toolSpecOf: (value: unknown) => ToolSpec | undefined;
 /** A tool file's default export. */
 export type ToolExport = Tool | ReadonlyArray<Tool>;

package/dist/authoring/index.js

@@ -1,23 +1,33 @@
 import {
   __enterFile,
   __leaveFile,
+  basic,
+  bearer,
   defineApp,
+  defineDynamicTools,
   defineTool,
+  dynamicSpecOf,
   newRegistry,
   oauth,
+  recordAuthoringProblem,
   requirementSpecOf,
   secrets,
   service,
   setActiveRegistry,
   toolSpecOf
-} from "../chunk-LWKQDDLZ.js";
+} from "../chunk-A3H32P2J.js";
 export {
   __enterFile,
   __leaveFile,
+  basic,
+  bearer,
   defineApp,
+  defineDynamicTools,
   defineTool,
+  dynamicSpecOf,
   newRegistry,
   oauth,
+  recordAuthoringProblem,
   requirementSpecOf,
   secrets,
   service,

package/dist/{chunk-NFLNA2SC.js → chunk-4OZFMCTT.js}

@@ -5,7 +5,13 @@ var CallError = class extends Data.TaggedError("CallError") {
     return `${this.target}: ${this.reason}`;
   }
 };
+var DiscoverError = class extends Data.TaggedError("DiscoverError") {
+  get message() {
+    return `${this.segment}: ${this.reason}`;
+  }
+};
 
 export {
-  CallError
+  CallError,
+  DiscoverError
 };

package/dist/{chunk-LWKQDDLZ.js → chunk-A3H32P2J.js}

@@ -1,8 +1,44 @@
 // src/authoring/index.ts
+var bearer = (opts) => ({ kind: "bearer", ...opts });
+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 recordAuthoringProblem = (message) => {
+  const file = sourceFileFor("wrapper");
+  activeRegistry.problems.push({ message: `${file}: ${message}` });
+};
 var DynamicKey = Symbol.for("executor/apps/dynamic");
+var dynamicSpecOf = (value) => typeof value === "object" && value !== null && DynamicKey in value ? value[DynamicKey] : void 0;
+var defineDynamicTools = (decl) => {
+  const spec = decl;
+  const file = sourceFileFor("defineDynamicTools(...)");
+  const problems = [];
+  if (typeof spec.description !== "string" || spec.description.trim().length === 0)
+    problems.push("dynamic tool set description must not be empty");
+  const roles = Object.entries(spec.requirements ?? {});
+  if (roles.length > 1) problems.push("a dynamic tool set takes exactly one requirement role");
+  else if (roles.length === 1) {
+    const [role, value] = roles[0];
+    const requirementSpec = requirementSpecOf(value);
+    if (requirementSpec === void 0)
+      problems.push(`requirement '${role}' is not a service/requirement value`);
+    else if (requirementSpec.arity === "many")
+      problems.push(
+        `requirement '${role}' cannot be .array() \u2014 multiple accounts expand the catalog per connection, never merge one list`
+      );
+  }
+  if (problems.length > 0) {
+    activeRegistry.problems.push(...problems.map((message) => ({ message: `${file}: ${message}` })));
+    return { [DynamicKey]: void 0 };
+  }
+  if (activeRegistry.dynamic.has(file))
+    activeRegistry.problems.push({
+      message: `${file}: one dynamic tool set per file \u2014 its address segment is the file's name`
+    });
+  else activeRegistry.dynamic.set(file, { spec, file });
+  return { [DynamicKey]: spec };
+};
 var newRegistry = () => ({
   app: void 0,
   services: /* @__PURE__ */ new Map(),
@@ -61,7 +97,11 @@ var defineApp = (manifest) => {
   return value;
 };
 var ToolKey = Symbol.for("executor/apps/tool");
-var defineTool = (spec) => {
+var defineTool = (decl) => {
+  const spec = decl;
+  return registerTool(spec);
+};
+var registerTool = (spec) => {
   const file = sourceFileFor("defineTool(...)");
   const value = { [ToolKey]: spec };
   const fileName = file.slice(file.lastIndexOf("/") + 1);
@@ -84,8 +124,13 @@ var isTool = (value) => typeof value === "object" && value !== null && ToolKey i
 var toolSpecOf = (value) => isTool(value) ? value[ToolKey] : void 0;
 
 export {
+  bearer,
+  basic,
   secrets,
   oauth,
+  recordAuthoringProblem,
+  dynamicSpecOf,
+  defineDynamicTools,
   newRegistry,
   setActiveRegistry,
   __enterFile,

package/dist/chunk-F7GZYEAC.js

@@ -0,0 +1,41 @@
+import {
+  defineDynamicTools,
+  recordAuthoringProblem,
+  requirementSpecOf
+} from "./chunk-A3H32P2J.js";
+
+// src/openapi/mapper.ts
+var openapiDiscover = async (_spec, _ctx, _auth, _operations) => {
+  throw new Error("openapi mapper not built yet");
+};
+var openapiCall = async (_tool, _input, _ctx, _auth) => {
+  throw new Error("openapi mapper not built yet");
+};
+
+// src/openapi/index.ts
+var enforceSecretsPlacement = (requirements, auth) => {
+  if (auth !== void 0) return;
+  for (const value of Object.values(requirements ?? {})) {
+    const spec = requirementSpecOf(value);
+    const methods = spec?.grant === void 0 ? Object.values(spec?.service.auth ?? {}) : [spec.service.auth?.[spec.grant]].filter((method) => method !== void 0);
+    if (methods.some((method) => method.kind === "secrets"))
+      recordAuthoringProblem(
+        "fromOpenAPI: the service offers a secrets() auth method, so 'auth' must state how the credential rides"
+      );
+  }
+};
+function fromOpenAPI(spec, options) {
+  enforceSecretsPlacement(options?.requirements, options?.auth);
+  const auth = options?.auth;
+  const operations = options?.operations;
+  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)
+  });
+}
+
+export {
+  fromOpenAPI
+};