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

package/src/mcp/index.ts

@@ -0,0 +1,42 @@
+/** fromMCP sugar over the authored dynamic-tools primitive. */
+
+import {
+  defineDynamicTools,
+  type AuthComposeFn,
+  type DynamicToolSet,
+  type OperationSelection,
+  type Requirement,
+} from "../authoring/index";
+import { mcpCall, mcpDiscover } from "./client";
+
+export type FromMCPOptions<Reqs extends Readonly<Record<string, Requirement>>> = {
+  readonly requirements: Reqs;
+  readonly auth?: AuthComposeFn<NoInfer<Reqs>>;
+  readonly operations?: OperationSelection;
+};
+
+export function fromMCP<const Reqs extends Readonly<Record<string, Requirement>>>(
+  endpoint: string,
+  options: FromMCPOptions<Reqs>,
+): DynamicToolSet;
+export function fromMCP(
+  endpoint: string,
+  options?: { readonly operations?: OperationSelection },
+): DynamicToolSet;
+export function fromMCP(
+  endpoint: string,
+  options?: {
+    readonly requirements?: Readonly<Record<string, Requirement>>;
+    readonly auth?: AuthComposeFn<never>;
+    readonly operations?: OperationSelection;
+  },
+): DynamicToolSet {
+  const auth = options?.auth;
+  const operations = options?.operations;
+  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),
+  });
+}

package/src/openapi/index.ts

@@ -0,0 +1,70 @@
+/** fromOpenAPI sugar over the authored dynamic-tools primitive. */
+
+import {
+  defineDynamicTools,
+  recordAuthoringProblem,
+  requirementSpecOf,
+  type AuthComposeFn,
+  type DynamicToolSet,
+  type OperationSelection,
+  type Requirement,
+  type RequiresAuthCompose,
+} from "../authoring/index";
+import { openapiCall, openapiDiscover } from "./mapper";
+
+export type FromOpenAPIOptions<Reqs extends Readonly<Record<string, Requirement>>> = {
+  readonly requirements: Reqs;
+  readonly auth?: AuthComposeFn<NoInfer<Reqs>>;
+  readonly operations?: OperationSelection;
+} & (RequiresAuthCompose<Reqs> extends true
+  ? { readonly auth: AuthComposeFn<NoInfer<Reqs>> }
+  : unknown);
+
+const enforceSecretsPlacement = (
+  requirements: Readonly<Record<string, Requirement>> | undefined,
+  auth: AuthComposeFn<never> | undefined,
+): void => {
+  if (auth !== undefined) return;
+  for (const value of Object.values(requirements ?? {})) {
+    const spec = requirementSpecOf(value);
+    const methods = spec?.grant === undefined
+      ? Object.values(spec?.service.auth ?? {})
+      : [spec.service.auth?.[spec.grant]].filter((method) => method !== undefined);
+    if (methods.some((method) => method.kind === "secrets"))
+      recordAuthoringProblem(
+        "fromOpenAPI: the service offers a secrets() auth method, so 'auth' must state how the credential rides",
+      );
+  }
+};
+
+export type OpenAPIDocumentInput = string | Readonly<Record<string, unknown>>;
+
+export function fromOpenAPI<const Reqs extends Readonly<Record<string, Requirement>>>(
+  spec: OpenAPIDocumentInput,
+  options: FromOpenAPIOptions<Reqs>,
+): DynamicToolSet;
+export function fromOpenAPI(
+  spec: OpenAPIDocumentInput,
+  options?: { readonly operations?: OperationSelection },
+): DynamicToolSet;
+export function fromOpenAPI(
+  spec: OpenAPIDocumentInput,
+  options?: {
+    readonly requirements?: Readonly<Record<string, Requirement>>;
+    readonly auth?: AuthComposeFn<never>;
+    readonly operations?: OperationSelection;
+  },
+): DynamicToolSet {
+  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 === undefined ? {} : { requirements: options.requirements }),
+    discover: (ctx) => openapiDiscover(spec, ctx, auth, operations),
+    call: (tool, input, ctx) => openapiCall(tool, input, ctx, auth),
+  });
+}

package/src/openapi/mapper.ts

@@ -0,0 +1,25 @@
+/** Stub-contract OpenAPI discovery and call mapper. */
+
+import type {
+  AuthComposeFn,
+  DiscoveredToolSpec,
+  OperationSelection,
+} from "../authoring/index";
+
+export const openapiDiscover = async (
+  _spec: string | Readonly<Record<string, unknown>>,
+  _ctx: unknown,
+  _auth: AuthComposeFn<never> | undefined,
+  _operations: OperationSelection | undefined,
+): Promise<readonly DiscoveredToolSpec[]> => {
+  throw new Error("openapi mapper not built yet");
+};
+
+export const openapiCall = async (
+  _tool: { readonly name: string; readonly detail: unknown },
+  _input: unknown,
+  _ctx: unknown,
+  _auth: AuthComposeFn<never> | undefined,
+): Promise<unknown> => {
+  throw new Error("openapi mapper not built yet");
+};

package/src/runner/index.ts

@@ -4,8 +4,13 @@ import {
   type LoadedApp,
   type PublishError,
 } from "../manifest/index";
-import { callTool, discoverTool, type CallOutcome } from "../runtime/index";
-import { CallError, type AppRunner } from "./protocol";
+import {
+  callTool,
+  discoverTool,
+  type CallOutcome,
+  type DiscoverOutcome,
+} from "../runtime/index";
+import { CallError, DiscoverError, type AppRunner } from "./protocol";
 
 export * from "./protocol";
 
@@ -30,28 +35,46 @@ export const localRunner = (appDir: string): AppRunner => {
     loaded().pipe(
       Effect.map(({ registry }) => registry),
       Effect.mapError(
-        (error) => new CallError({ target, reason: `app failed to load (${error.message})` }),
+        (error) => new CallError({
+          target,
+          kind: "handler",
+          reason: `app failed to load (${error.message})`,
+        }),
       ),
     );
 
   const settle = (target: string, outcome: CallOutcome): Effect.Effect<unknown, CallError> =>
     outcome.ok
       ? Effect.succeed(outcome.value)
-      : Effect.fail(new CallError({ target, reason: outcome.reason }));
+      : Effect.fail(new CallError({
+          target,
+          kind: outcome.kind,
+          reason: outcome.reason,
+        }));
+
+  const settleDiscovery = (
+    segment: string,
+    outcome: DiscoverOutcome,
+  ) => outcome.ok
+    ? Effect.succeed(outcome.value)
+    : Effect.fail(new DiscoverError({ segment, reason: outcome.reason }));
 
   return {
     manifest: () => Effect.map(loaded(), ({ result }) => result),
-    call: (name, input, ctx) =>
-      registryFor(name).pipe(
-        Effect.flatMap((registry) => Effect.promise(() => callTool(registry, name, input, ctx))),
-        Effect.flatMap((outcome) => settle(name, outcome)),
+    call: (address, input, ctx, detail) =>
+      registryFor(address).pipe(
+        Effect.flatMap((registry) =>
+          Effect.promise(() => callTool(registry, address, input, ctx, detail)),
+        ),
+        Effect.flatMap((outcome) => settle(address, outcome)),
       ),
-    discover: (name, binding) =>
-      registryFor(name).pipe(
+    discover: (segment, ctx) =>
+      registryFor(segment).pipe(
+        Effect.mapError((error) => new DiscoverError({ segment, reason: error.reason })),
         Effect.flatMap((registry) =>
-          Effect.promise(() => discoverTool(registry, name, binding)),
+          Effect.promise(() => discoverTool(registry, segment, ctx)),
         ),
-        Effect.flatMap((outcome) => settle(name, outcome)),
+        Effect.flatMap((outcome) => settleDiscovery(segment, outcome)),
       ),
   };
 };

package/src/runner/protocol.ts

@@ -1,12 +1,26 @@
 import { Data, type Effect, FileSystem } from "effect";
 import type { AppManifestResult, PublishError } from "../manifest/contract";
-import type { ToolCtx, ToolCtxEntry } from "../runtime/index";
+import type {
+  CallFailureKind,
+  DiscoveredTool,
+  ToolCtx,
+  ToolCtxEntry,
+} from "../runtime/index";
 
-export type { ToolCtx, ToolCtxEntry } from "../runtime/index";
+export type {
+  DiscoveredTool,
+  ToolCtx,
+  ToolCtxEntry,
+  ToolDescriptor,
+} from "../runtime/index";
 
-/** A runner operation failure associated with its target. */
+/** Which invocation phase failed. */
+export type CallErrorKind = CallFailureKind;
+
+/** A runner operation failure associated with its target and phase. */
 export class CallError extends Data.TaggedError("CallError")<{
   readonly target: string;
+  readonly kind: CallErrorKind;
   readonly reason: string;
 }> {
   override get message(): string {
@@ -14,16 +28,27 @@ export class CallError extends Data.TaggedError("CallError")<{
   }
 }
 
+/** A discovery failure associated with one dynamic segment. */
+export class DiscoverError extends Data.TaggedError("DiscoverError")<{
+  readonly segment: string;
+  readonly reason: string;
+}> {
+  override get message(): string {
+    return `${this.segment}: ${this.reason}`;
+  }
+}
+
 /** The platform protocol implemented by an app execution environment. */
 export interface AppRunner {
   manifest(): Effect.Effect<AppManifestResult, PublishError, FileSystem.FileSystem>;
   call(
-    name: string,
+    address: string,
     input: unknown,
     ctx: ToolCtx,
+    detail?: unknown,
   ): Effect.Effect<unknown, CallError, FileSystem.FileSystem>;
   discover(
-    name: string,
-    binding: unknown,
-  ): Effect.Effect<unknown, CallError, FileSystem.FileSystem>;
+    segment: string,
+    ctx: ToolCtx,
+  ): Effect.Effect<readonly DiscoveredTool[], DiscoverError, FileSystem.FileSystem>;
 }

package/src/runtime/index.ts

@@ -12,12 +12,17 @@
  * and workerd all provide.
  */
 
-import type { Registry, ToolSpec } from "../authoring/index";
+import type {
+  DiscoveredToolSpec,
+  DynamicToolsSpec,
+  Registry,
+} from "../authoring/index";
 import type {
   AppManifestResult,
   CollectedClaim,
   CollectedRequirement,
   JsonSchemaObject,
+  ManifestDynamic,
   ManifestTool,
 } from "../manifest/contract";
 
@@ -26,7 +31,10 @@ import type {
 /** The capability exposed to one tool requirement role. */
 export interface ToolCtxEntry {
   readonly grant: string;
+  readonly kind: "bearer" | "basic" | "secrets" | "oauth";
   readonly token?: string;
+  readonly username?: string;
+  readonly password?: string;
   readonly secrets?: Readonly<Record<string, string>>;
   fetch(path: string, init?: RequestInit): Promise<Response>;
 }
@@ -41,12 +49,46 @@ export type ManifestOutcome =
   | { readonly ok: true; readonly result: AppManifestResult }
   | { readonly ok: false; readonly problems: readonly string[] };
 
+/** Which invocation phase failed. */
+export type CallFailureKind = "input" | "handler";
+
 /** One tool invocation's result envelope. */
 export type CallOutcome =
   | { readonly ok: true; readonly value: unknown }
+  | {
+      readonly ok: false;
+      readonly kind: CallFailureKind;
+      readonly reason: string;
+    };
+
+/** Agent-facing descriptor compiled from one discovery result. */
+export interface ToolDescriptor {
+  readonly description: string;
+  readonly inputSchema: JsonSchemaObject;
+  readonly annotations: {
+    readonly readOnly?: boolean;
+    readonly destructive?: boolean;
+  };
+}
+
+/** One tool emitted by a dynamic segment discovery. */
+export interface DiscoveredTool {
+  readonly segment: string;
+  readonly name: string;
+  readonly descriptor: ToolDescriptor;
+  readonly detail: unknown;
+}
+
+/** One dynamic discovery result envelope. */
+export type DiscoverOutcome =
+  | { readonly ok: true; readonly value: readonly DiscoveredTool[] }
   | { readonly ok: false; readonly reason: string };
 
-const failure = (reason: string): CallOutcome => ({ ok: false, reason });
+const failure = (kind: CallFailureKind, reason: string): CallOutcome => ({
+  ok: false,
+  kind,
+  reason,
+});
 
 const errorMessage = (error: unknown): string =>
   error instanceof Error ? error.message : String(error);
@@ -106,7 +148,7 @@ type InputSchemaCompilation =
   | { readonly value: JsonSchemaObject }
   | { readonly problem: string };
 
-const compileInputSchema = (input: object, where: string): InputSchemaCompilation => {
+export const compileInputSchema = (input: object, where: string): InputSchemaCompilation => {
   const standard = standardJsonSchemaOf(input);
   if ("~standard" in input && typeof standard?.input !== "function")
     return {
@@ -152,6 +194,11 @@ const requirementSpecOf = (value: unknown): RequirementSpecShape | undefined =>
     ? ((value as Record<PropertyKey, unknown>)[requirementKey] as RequirementSpecShape)
     : undefined;
 
+const segmentOf = (file: string): string => {
+  const name = file.slice(file.lastIndexOf("/") + 1);
+  return name.endsWith(".ts") ? name.slice(0, -3) : name;
+};
+
 const canonicalJson = (value: unknown): string => {
   const sortKeys = (node: unknown): unknown => {
     if (Array.isArray(node)) return node.map(sortKeys);
@@ -170,6 +217,7 @@ interface CollectedManifest {
   readonly app: { readonly key: string; readonly label: string; readonly description: string };
   readonly services: readonly CollectedClaim[];
   readonly tools: readonly ManifestTool[];
+  readonly dynamic: readonly ManifestDynamic[];
 }
 
 type RegistryCollection =
@@ -229,6 +277,8 @@ const collectRegistry = (registry: Registry): RegistryCollection => {
   for (const [file, summary] of registry.toolFiles) {
     if (summary.definitions > 1 && summary.hasUnnamedTool)
       problems.push(`${file}: multi-tool files must name every tool`);
+    if (registry.dynamic.has(file))
+      problems.push(`${file}: a file claims a dynamic tool set or defines tools, never both`);
   }
 
   const tools: ManifestTool[] = [];
@@ -261,13 +311,47 @@ const collectRegistry = (registry: Registry): RegistryCollection => {
     }
   }
 
+  const dynamic: ManifestDynamic[] = [];
+  const seenSegments = new Map<string, string>();
+  for (const [file, registered] of registry.dynamic) {
+    const segment = segmentOf(file);
+    const where = `${file}: dynamic tool set '${segment}'`;
+    const existing = seenSegments.get(segment);
+    if (existing !== undefined) {
+      problems.push(`${where}: segment already claimed by ${existing}`);
+      continue;
+    }
+    seenSegments.set(segment, file);
+
+    const requires = Object.entries(registered.spec.requirements ?? {})
+      .flatMap(([role, requirement]) => {
+        const collected = collectRequirement(role, requirement, where);
+        return collected === undefined ? [] : [collected];
+      })
+      .sort((left, right) => left.role.localeCompare(right.role));
+    dynamic.push({
+      segment,
+      description: registered.spec.description,
+      requires,
+      file,
+    });
+  }
+
   if (problems.length > 0 || app === undefined) return { problems };
   const services = [...claims.values()].sort((left, right) =>
     left.origin.localeCompare(right.origin),
   );
   const sortedTools = [...tools].sort((left, right) => left.address.localeCompare(right.address));
+  const sortedDynamic = [...dynamic].sort((left, right) =>
+    left.segment.localeCompare(right.segment),
+  );
   const appResult = { key: app.key, label: app.label, description: app.description };
-  const manifest = { app: appResult, services, tools: sortedTools } satisfies CollectedManifest;
+  const manifest = {
+    app: appResult,
+    services,
+    tools: sortedTools,
+    dynamic: sortedDynamic,
+  } satisfies CollectedManifest;
   return { problems: [], manifest, canonical: canonicalJson(manifest) };
 };
 
@@ -314,8 +398,8 @@ type ParsedInput =
   | { readonly ok: true; readonly value: unknown }
   | { readonly ok: false; readonly reason: string };
 
-const parseInput = async (spec: ToolSpec, input: unknown): Promise<ParsedInput> => {
-  const validate = standardValidateOf(spec.input);
+const parseInput = async (schema: object, input: unknown): Promise<ParsedInput> => {
+  const validate = standardValidateOf(schema);
   if (validate === undefined)
     return { ok: false, reason: "input schema does not implement Standard Schema validate" };
   try {
@@ -331,33 +415,136 @@ const parseInput = async (spec: ToolSpec, input: unknown): Promise<ParsedInput>
   }
 };
 
-/** Validate input and run one registered tool's handler. */
+const splitDynamicAddress = (
+  address: string,
+): { readonly segment: string; readonly name: string } | undefined => {
+  const slash = address.indexOf("/");
+  if (slash <= 0 || slash === address.length - 1) return undefined;
+  return { segment: address.slice(0, slash), name: address.slice(slash + 1) };
+};
+
+const dynamicFor = (
+  registry: Registry,
+  segment: string,
+): DynamicToolsSpec | undefined => {
+  for (const [file, registered] of registry.dynamic)
+    if (segmentOf(file) === segment) return registered.spec;
+  return undefined;
+};
+
+/** Live schemas from the latest successful discovery, retained per loaded registry. */
+const discoveredSpecs = new WeakMap<
+  Registry,
+  Map<string, ReadonlyMap<string, DiscoveredToolSpec>>
+>();
+
+/** Validate input and run one static or dynamic tool handler. */
 export const callTool = async (
   registry: Registry,
-  name: string,
+  address: string,
   input: unknown,
   ctx: ToolCtx,
+  detail?: unknown,
 ): Promise<CallOutcome> => {
-  const registered = registry.tools.get(name);
-  if (registered === undefined) return failure("unknown tool");
-  const parsed = await parseInput(registered.spec, input);
-  if (!parsed.ok) return parsed;
+  const dynamic = splitDynamicAddress(address);
+  if (dynamic === undefined) {
+    if (detail !== undefined)
+      return failure("handler", "a static tool takes no discovery detail");
+    const registered = registry.tools.get(address);
+    if (registered === undefined) return failure("handler", "unknown tool");
+    const parsed = await parseInput(registered.spec.input, input);
+    if (!parsed.ok) return failure("input", parsed.reason);
+    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) };
+    } catch (error) {
+      return failure("handler", `handler failed (${errorMessage(error)})`);
+    }
+  }
+
+  if (detail === undefined)
+    return failure("handler", "a dynamic tool requires discovery detail");
+  const pair = dynamicFor(registry, dynamic.segment);
+  if (pair === undefined)
+    return failure("handler", `unknown dynamic tool set '${dynamic.segment}'`);
+  const discovered = discoveredSpecs.get(registry)?.get(dynamic.segment)?.get(dynamic.name);
+  if (discovered === undefined)
+    return failure(
+      "input",
+      `dynamic tool '${dynamic.name}' has no compiled discovery descriptor`,
+    );
+  const parsed = await parseInput(discovered.input, input);
+  if (!parsed.ok) return failure("input", parsed.reason);
   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 (
+    const call = pair.call as (
+      tool: { readonly name: string; readonly detail: unknown },
       value: unknown,
       toolCtx: ToolCtx,
     ) => Promise<unknown>;
-    return { ok: true, value: await handler(parsed.value, ctx) };
+    return {
+      ok: true,
+      value: await call({ name: dynamic.name, detail }, parsed.value, ctx),
+    };
   } catch (error) {
-    return failure(`handler failed (${errorMessage(error)})`);
+    return failure("handler", `dynamic call failed (${errorMessage(error)})`);
   }
 };
 
-/** Discover one dynamic tool set's current segment. Unbuilt: always fails. */
+/** Discover and compile one dynamic segment. */
 export const discoverTool = async (
-  _registry: Registry,
-  _name: string,
-  _binding: unknown,
-): Promise<CallOutcome> => failure("no dynamic tools yet");
+  registry: Registry,
+  segment: string,
+  ctx: ToolCtx,
+): Promise<DiscoverOutcome> => {
+  const pair = dynamicFor(registry, segment);
+  if (pair === undefined)
+    return { ok: false, reason: `unknown dynamic tool set '${segment}'` };
+  discoveredSpecs.get(registry)?.delete(segment);
+
+  let emitted: readonly DiscoveredToolSpec[];
+  try {
+    const discover = pair.discover as (
+      toolCtx: ToolCtx,
+    ) => Promise<readonly DiscoveredToolSpec[]>;
+    emitted = await discover(ctx);
+  } catch (error) {
+    return { ok: false, reason: `discover failed (${errorMessage(error)})` };
+  }
+
+  const tools: DiscoveredTool[] = [];
+  const live = new Map<string, DiscoveredToolSpec>();
+  for (const tool of emitted) {
+    if (live.has(tool.name))
+      return { ok: false, reason: `discover emitted duplicate tool '${tool.name}'` };
+    const compiled = compileInputSchema(tool.input, `${segment}/${tool.name}`);
+    if ("problem" in compiled) return { ok: false, reason: compiled.problem };
+    live.set(tool.name, tool);
+    tools.push({
+      segment,
+      name: tool.name,
+      descriptor: {
+        description: tool.description,
+        inputSchema: compiled.value,
+        annotations: {
+          ...(tool.annotations?.readOnly === undefined
+            ? {}
+            : { readOnly: tool.annotations.readOnly }),
+          ...(tool.annotations?.destructive === undefined
+            ? {}
+            : { destructive: tool.annotations.destructive }),
+        },
+      },
+      detail: tool.detail ?? null,
+    });
+  }
+
+  const registryDiscoveries = discoveredSpecs.get(registry) ?? new Map();
+  registryDiscoveries.set(segment, live);
+  discoveredSpecs.set(registry, registryDiscoveries);
+  return { ok: true, value: tools.sort((left, right) => left.name.localeCompare(right.name)) };
+};

package/src/workerd/index.ts

@@ -9,6 +9,8 @@ export {
   discoverTool,
   manifestOf,
   type CallOutcome,
+  type DiscoverOutcome,
+  type DiscoveredTool,
   type ManifestOutcome,
   type ToolCtx,
   type ToolCtxEntry,