apps 1.0.0-beta.1 → 1.0.0-beta.3

package/src/authoring/index.ts

@@ -5,6 +5,24 @@
  */
 
 // ── auth options (auth methods) ──────────────────────────────────────────────
+//
+// An auth method states the credential's kind, never its placement.
+// bearer/basic/oauth have protocol-defined spend semantics. secrets()
+// is the anonymous bag whose spend must be authored at the surface.
+
+/** 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>>,
@@ -24,7 +42,7 @@ export interface SecretField {
 }
 
 /**
- * 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
@@ -49,7 +67,17 @@ export interface OAuthMethod {
   readonly paste?: false;
 }
 
-export type AuthMethod = SecretsMethod | OAuthMethod;
+export type AuthMethod = BearerMethod | BasicMethod | SecretsMethod | OAuthMethod;
+
+export const bearer = (opts: {
+  readonly label: string;
+  readonly help?: string;
+}): BearerMethod => ({ kind: "bearer", ...opts });
+
+export const basic = (opts: {
+  readonly label: string;
+  readonly help?: string;
+}): BasicMethod => ({ kind: "basic", ...opts });
 
 export const secrets = <const F extends Readonly<Record<string, SecretField>>>(opts: {
   readonly label: string;
@@ -99,23 +127,44 @@ export interface RequirementSpec {
 
 const RequirementKey: unique symbol = Symbol.for("executor/apps/requirement");
 
+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. */
@@ -125,39 +174,217 @@ export interface Problem {
 
 // ── dynamic tool sets ─────────────────────────────────────────────────
 
+/** 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: "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 const recordAuthoringProblem = (message: string): void => {
+  const file = sourceFileFor("wrapper");
+  activeRegistry.problems.push({ message: `${file}: ${message}` });
+};
+
+/** 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;
+}
+
 /**
- * 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.
+ * 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 type DynamicClaimSpec =
-  | {
-      readonly kind: "mcp";
-      readonly requirement: RequirementSpec;
-      /** MCP endpoint URL. Absent = the service origin at its root path. */
-      readonly endpoint?: string;
-    }
-  | {
-      readonly kind: "openapi";
-      readonly requirement: RequirementSpec;
-      /** OpenAPI document: an absolute URL or an app-relative path. */
-      readonly spec: string;
-    };
+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>;
+}
 
 const DynamicKey: unique symbol = Symbol.for("executor/apps/dynamic");
 
-/** 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 const dynamicSpecOf = (value: unknown): DynamicToolsSpec | undefined =>
+  typeof value === "object" && value !== null && DynamicKey in value
+    ? (value as DynamicToolSet)[DynamicKey]
+    : 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 const defineDynamicTools = <
+  const Reqs extends Readonly<Record<string, Requirement>> | undefined = undefined,
+>(decl: DynamicToolsDecl<Reqs>): DynamicToolSet => {
+  // SAFETY: same erasure boundary as defineTool — members identical,
+  // handler parameter types narrow to the registry's untyped floor.
+  const spec = decl as unknown as DynamicToolsSpec;
+  const file = sourceFileFor("defineDynamicTools(...)");
+  const problems: string[] = [];
+
+  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 === undefined)
+      problems.push(`requirement '${role}' is not a service/requirement value`);
+    else if (requirementSpec.arity === "many")
+      problems.push(
+        `requirement '${role}' cannot be .array() — 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]: undefined };
+  }
+
+  if (activeRegistry.dynamic.has(file))
+    activeRegistry.problems.push({
+      message: `${file}: one dynamic tool set per file — its address segment is the file's name`,
+    });
+  else activeRegistry.dynamic.set(file, { spec, file });
+  return { [DynamicKey]: spec };
+};
+
+/** A registered dynamic tool set and its source attribution. @internal */
+export interface DynamicRegistration {
+  readonly spec: DynamicToolsSpec;
   readonly file: string;
 }
 
@@ -178,7 +405,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,
@@ -224,22 +451,29 @@ const sourceFileFor = (claim: string): string => {
   return "<unattributed>";
 };
 
-const makeTerminal = <D extends ServiceDecl>(spec: RequirementSpec): Requirement<D> => ({
+const makeTerminal = <
+  D extends ServiceDecl,
+  G extends string | undefined,
+  A extends RequirementArity,
+>(spec: RequirementSpec): Requirement<D, G, A> => ({
   [RequirementKey]: spec,
-  describe: (text) => makeTerminal<D>({ ...spec, description: text }),
+  describe: (text) => makeTerminal<D, G, A>({ ...spec, description: text }),
 });
 
 export const service = <const D extends ServiceDecl>(decl: D): Service<D> => {
   const file = sourceFileFor("service(...)");
-  const make = (spec: RequirementSpec): Service<D> => ({
+  const make = <G extends (keyof NonNullable<D["auth"]> & string) | undefined>(
+    spec: RequirementSpec,
+  ): Service<D, G> => ({
     [RequirementKey]: spec,
     decl,
-    optional: () => makeTerminal<D>({ ...spec, arity: "optional" }),
-    array: () => makeTerminal<D>({ ...spec, arity: "many" }),
-    grant: (name) => make({ ...spec, grant: name }),
-    describe: (text) => make({ ...spec, description: text }),
+    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 }),
   });
-  const value = make({ service: decl, arity: "one" });
+  const value = make<undefined>({ service: decl, arity: "one" });
   if (!activeRegistry.services.has(decl.origin))
     activeRegistry.services.set(decl.origin, { decl, file });
   return value;
@@ -284,6 +518,47 @@ export const defineApp = (manifest: {
 /** 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;
@@ -291,8 +566,40 @@ export interface ToolAnnotations {
   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>>;
@@ -308,7 +615,18 @@ export interface Tool {
   readonly [ToolKey]: ToolSpec;
 }
 
-export const defineTool = (spec: ToolSpec): Tool => {
+export 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 => {
+  // SAFETY: the erased row keeps the same members; only the handler's
+  // parameter types narrow (never is the bottom of every inference).
+  const spec = decl as unknown as ToolSpec;
+  return registerTool(spec);
+};
+
+const registerTool = (spec: ToolSpec): Tool => {
   const file = sourceFileFor("defineTool(...)");
   const value: Tool = { [ToolKey]: spec };
   const fileName = file.slice(file.lastIndexOf("/") + 1);

package/src/http/index.ts

@@ -0,0 +1,26 @@
+/** HTTP credential placement helpers for kind-bearing connected roles. */
+
+import type { RoleMaterial } from "../authoring/index";
+
+export type HttpSpendableRole = Extract<
+  RoleMaterial,
+  { kind: "bearer" | "oauth" | "basic" }
+>;
+
+/** Build the protocol-defined Authorization header for a connected role. */
+export const authHeaders = (role: HttpSpendableRole): { readonly authorization: string } => {
+  switch (role.kind) {
+    case "bearer":
+    case "oauth":
+      return { authorization: `Bearer ${role.token}` };
+    case "basic":
+      return { authorization: `Basic ${base64(`${role.username}:${role.password}`)}` };
+  }
+};
+
+const base64 = (value: string): string => {
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+};

package/src/index.ts

@@ -1,9 +1,4 @@
-/**
- * The authoring surface: what app code imports. Pure and synchronous —
- * no effect dependency, no node builtins — so authored files run
- * unmodified in any execution environment, including sandboxed workers.
- *
- * Host-side machinery lives behind subpaths: "apps/manifest" loads and
- * validates authored sources, "apps/runner" executes them.
- */
 export * from "./authoring/index";
+export * from "./http/index";
+export * from "./mcp/index";
+export * from "./openapi/index";

package/src/manifest/contract.ts

@@ -37,12 +37,21 @@ export interface ManifestTool {
   readonly file: string;
 }
 
+/** A dynamic address segment projected without endpoint or specification data. */
+export interface ManifestDynamic {
+  readonly segment: string;
+  readonly description: string;
+  readonly requires: readonly CollectedRequirement[];
+  readonly file: string;
+}
+
 /** The deterministic public description of an executor app. */
 export interface AppManifestResult {
   readonly digest: string;
   readonly app: { readonly key: string; readonly label: string; readonly description: string };
   readonly services: readonly CollectedClaim[];
   readonly tools: readonly ManifestTool[];
+  readonly dynamic: readonly ManifestDynamic[];
 }
 
 /** All publish-time authoring problems from one registry load. */