apps 0.8.3 → 1.0.0-beta.0

package/src/authoring/index.ts

@@ -0,0 +1,340 @@
+/**
+ * Synchronous authoring primitives imported by app.ts and tools/*.ts.
+ * Authored modules record plain claims without I/O or user context; the
+ * manifest loader owns execution, validation, and effects.
+ */
+
+// ── auth options (auth methods) ──────────────────────────────────────────────
+
+export interface SecretsMethod<
+  F extends Readonly<Record<string, SecretField>> = Readonly<Record<string, SecretField>>,
+> {
+  readonly kind: "secrets";
+  readonly label: string;
+  /** Markdown shown under this auth method on the connect page, for example:
+   * "Create a fine-grained token at github.com/settings/tokens." */
+  readonly help?: string;
+  readonly fields: F;
+}
+
+export interface SecretField {
+  readonly label: string;
+  /** Form masking. Stated, never guessed from the field name. */
+  readonly secret: boolean;
+}
+
+/**
+ * An oauth auth method is a secrets-shaped auth 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
+ * is the always-on floor (a pasted token spends identically), so the
+ * auth method works on any deployment; ceremony is progressive enhancement.
+ * Handlers cannot tell how material arrived.
+ */
+export interface OAuthMethod {
+  readonly kind: "oauth";
+  readonly label: string;
+  /** Markdown shown under this auth method on the connect page, for example:
+   * "Create a fine-grained token at github.com/settings/tokens." */
+  readonly help?: string;
+  /** Endpoints only when the service publishes no well-knowns —
+   * discovery (RFC 9728 + AS metadata) outranks these when present.
+   * Authors state facts about the service, never about the client. */
+  readonly authorizationEndpoint?: string;
+  readonly tokenEndpoint?: string;
+  readonly scopes?: readonly string[];
+  /** Set false only when a user-pasted token genuinely cannot work
+   * (audience-bound tokens, DPoP). Stated, never inferred. */
+  readonly paste?: false;
+}
+
+export type AuthMethod = SecretsMethod | OAuthMethod;
+
+export 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:
+   * "Create a fine-grained token at github.com/settings/tokens." */
+  readonly help?: string;
+  readonly fields: F;
+}): SecretsMethod<F> => ({ kind: "secrets", ...opts });
+
+export const oauth = (opts: {
+  readonly label: string;
+  /** Markdown shown under this auth method on the connect page, for example:
+   * "Create a fine-grained token at github.com/settings/tokens." */
+  readonly help?: string;
+  readonly authorizationEndpoint?: string;
+  readonly tokenEndpoint?: string;
+  readonly scopes?: readonly string[];
+  readonly paste?: false;
+}): OAuthMethod => ({ kind: "oauth", ...opts });
+
+// ── services ──────────────────────────────────────────────────────────
+
+export interface ServiceDecl {
+  /** Canonical origin, possibly templated: "https://{region}.posthog.com". */
+  readonly origin: string;
+  /** Hosts beyond the origin the credential legitimately travels to. */
+  readonly reach?: readonly string[];
+  /** Connection-scoped non-secret connect-form values; keys may fill
+   * origin templates. */
+  readonly params?: Readonly<Record<string, ParamSpec>>;
+  /** Named auth methods. Key = the grant name tools switch on. */
+  readonly auth?: Readonly<Record<string, AuthMethod>>;
+}
+
+export interface ParamSpec {
+  readonly label: string;
+  readonly options?: readonly string[];
+}
+
+/** What the manifest pipeline reads off a requirement value. */
+export interface RequirementSpec {
+  readonly service: ServiceDecl;
+  readonly arity: "one" | "optional" | "many";
+  readonly grant?: string;
+  readonly description?: string;
+}
+
+const RequirementKey: unique symbol = Symbol.for("executor/apps/requirement");
+
+/**
+ * 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.
+ */
+export interface Requirement<D extends ServiceDecl = ServiceDecl> {
+  readonly [RequirementKey]: RequirementSpec;
+  describe(text: string): Requirement<D>;
+}
+
+export interface Service<D extends ServiceDecl = ServiceDecl> extends Requirement<D> {
+  readonly decl: D;
+  optional(): Requirement<D>;
+  array(): Requirement<D>;
+  /** 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>;
+}
+
+/** A publish-time authoring problem accumulated without interrupting defines. */
+export interface Problem {
+  readonly message: string;
+}
+
+// ── dynamic tool sets ─────────────────────────────────────────────────
+
+/**
+ * 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;
+    }
+  | {
+      readonly kind: "openapi";
+      readonly requirement: RequirementSpec;
+      /** OpenAPI document: an absolute URL or an app-relative path. */
+      readonly spec: string;
+    };
+
+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
+ * invalid (a problem was recorded instead). */
+export interface DynamicToolSet {
+  readonly [DynamicKey]: DynamicClaimSpec | undefined;
+}
+
+/** A registered dynamic claim and its source attribution. @internal */
+export interface RegisteredDynamic {
+  readonly spec: DynamicClaimSpec;
+  readonly file: string;
+}
+
+/** A registered service declaration and its source attribution. @internal */
+export interface RegisteredService {
+  readonly decl: ServiceDecl;
+  readonly file: string;
+}
+
+/** A registered tool declaration and its source attribution. @internal */
+export interface RegisteredTool {
+  readonly spec: ToolSpec;
+  readonly file: string;
+}
+
+/** Mutable claim registry populated while authored modules execute. @internal */
+export interface Registry {
+  app: AppManifest | undefined;
+  readonly services: Map<string, RegisteredService>;
+  readonly tools: Map<string, RegisteredTool>;
+  readonly dynamic: Map<string, RegisteredDynamic>;
+  readonly problems: Problem[];
+  readonly toolFiles: Map<
+    string,
+    { definitions: number; hasUnnamedTool: boolean }
+  >;
+}
+
+/** Creates an isolated empty authoring registry. @internal */
+export const newRegistry = (): Registry => ({
+  app: undefined,
+  services: new Map(),
+  tools: new Map(),
+  dynamic: new Map(),
+  problems: [],
+  toolFiles: new Map(),
+});
+
+let activeRegistry = newRegistry();
+let currentFile: string | undefined;
+
+/** Swaps the registry receiving subsequent authoring claims. @internal */
+export const setActiveRegistry = (registry: Registry): Registry => {
+  const previous = activeRegistry;
+  activeRegistry = registry;
+  return previous;
+};
+
+/** Sets source-file attribution for subsequent authoring claims. @internal */
+export const __enterFile = (path: string): void => {
+  currentFile = path;
+};
+
+/** Clears source-file attribution after an authored module import. @internal */
+export const __leaveFile = (): void => {
+  currentFile = undefined;
+};
+
+const sourceFileFor = (claim: string): string => {
+  if (currentFile !== undefined) return currentFile;
+  activeRegistry.problems.push({
+    message: `${claim} called outside an authored module import`,
+  });
+  return "<unattributed>";
+};
+
+const makeTerminal = <D extends ServiceDecl>(spec: RequirementSpec): Requirement<D> => ({
+  [RequirementKey]: spec,
+  describe: (text) => makeTerminal<D>({ ...spec, description: text }),
+});
+
+export const service = <const D extends ServiceDecl>(decl: D): Service<D> => {
+  const file = sourceFileFor("service(...)");
+  const make = (spec: RequirementSpec): Service<D> => ({
+    [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 }),
+  });
+  const value = make({ service: decl, arity: "one" });
+  if (!activeRegistry.services.has(decl.origin))
+    activeRegistry.services.set(decl.origin, { decl, file });
+  return value;
+};
+
+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;
+
+export const requirementSpecOf = (value: unknown): RequirementSpec | undefined =>
+  isService(value) || isRequirement(value) ? value[RequirementKey] : undefined;
+
+// ── apps ──────────────────────────────────────────────────────────────
+
+export interface AppManifest {
+  readonly kind: "executor-app";
+  readonly key: string;
+  readonly label: string;
+  readonly description: string;
+}
+
+export const defineApp = (manifest: {
+  readonly key: string;
+  readonly label: string;
+  readonly description: string;
+}): AppManifest => {
+  const file = sourceFileFor("defineApp(...)");
+  const value: AppManifest = { kind: "executor-app", ...manifest };
+  if (activeRegistry.app === undefined) activeRegistry.app = value;
+  else activeRegistry.problems.push({ message: `${file}: duplicate defineApp(...)` });
+  return value;
+};
+
+// ── tools ─────────────────────────────────────────────────────────────
+
+/** Any Standard Schema (zod preferred) or a raw JSON-schema object. */
+export type SchemaLike = object;
+
+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 {
+  /** Address segment. Single-tool files may omit it (filename). */
+  readonly name?: string;
+  readonly description: string;
+  readonly requirements?: Readonly<Record<string, Requirement>>;
+  readonly input: SchemaLike;
+  readonly output?: SchemaLike;
+  readonly annotations?: ToolAnnotations;
+  handler(input: never, ctx: never): Promise<unknown>;
+}
+
+const ToolKey: unique symbol = Symbol.for("executor/apps/tool");
+
+export interface Tool {
+  readonly [ToolKey]: ToolSpec;
+}
+
+export const defineTool = (spec: ToolSpec): Tool => {
+  const file = sourceFileFor("defineTool(...)");
+  const value: Tool = { [ToolKey]: spec };
+  const fileName = file.slice(file.lastIndexOf("/") + 1);
+  const stem = fileName.endsWith(".ts") ? fileName.slice(0, -3) : fileName;
+  const name = spec.name ?? stem;
+  const fileSummary = activeRegistry.toolFiles.get(file);
+  activeRegistry.toolFiles.set(file, {
+    definitions: (fileSummary?.definitions ?? 0) + 1,
+    hasUnnamedTool: fileSummary?.hasUnnamedTool === true || spec.name === undefined,
+  });
+
+  const existing = activeRegistry.tools.get(name);
+  if (existing !== undefined) {
+    activeRegistry.problems.push({
+      message: `${file}: tool name '${name}' is already defined in ${existing.file}`,
+    });
+  } else activeRegistry.tools.set(name, { spec, file });
+
+  return value;
+};
+
+const isTool = (value: unknown): value is Tool =>
+  typeof value === "object" && value !== null && ToolKey in value;
+
+export const toolSpecOf = (value: unknown): ToolSpec | undefined =>
+  isTool(value) ? value[ToolKey] : undefined;
+
+/** A tool file's default export. */
+export type ToolExport = Tool | ReadonlyArray<Tool>;

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * 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";

package/src/manifest/collect.ts

@@ -0,0 +1,198 @@
+import type { AuthMethod, ParamSpec, Registry } from "../authoring/index";
+
+type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+  readonly [key: string]: JsonValue;
+};
+type JsonSchemaObject = Readonly<Record<string, JsonValue>>;
+
+interface CollectedClaim {
+  readonly origin: string;
+  readonly reach: readonly string[];
+  readonly params: Readonly<Record<string, ParamSpec>>;
+  readonly auth: Readonly<Record<string, AuthMethod>>;
+}
+
+interface CollectedRequirement {
+  readonly role: string;
+  readonly service: string;
+  readonly arity: "one" | "optional" | "many";
+  readonly grant?: string;
+  readonly description?: string;
+}
+
+interface CollectedTool {
+  readonly address: string;
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: JsonSchemaObject;
+  readonly annotations: {
+    readonly readOnly?: boolean;
+    readonly destructive?: boolean;
+    readonly scopes?: readonly string[];
+  };
+  readonly requires: readonly CollectedRequirement[];
+  readonly file: string;
+}
+
+interface CollectedManifest {
+  readonly app: { readonly key: string; readonly label: string; readonly description: string };
+  readonly services: readonly CollectedClaim[];
+  readonly tools: readonly CollectedTool[];
+}
+
+/** Result of compiling one authored input schema during registry projection. */
+export type InputSchemaCompilation =
+  | { readonly value: JsonSchemaObject }
+  | { readonly problem: string };
+
+/** Registry projection before the deployment-specific digest implementation. */
+export type RegistryCollection =
+  | { readonly problems: readonly string[] }
+  | {
+      readonly problems: readonly [];
+      readonly manifest: CollectedManifest;
+      readonly canonical: string;
+    };
+
+/**
+ * Validate and project an executed authoring registry into deterministic data.
+ *
+ * This function is deliberately closure-free: the workerd runner injects its
+ * source into the guest while the local manifest calls the same function
+ * directly. Schema compilation is supplied because each runtime owns its
+ * boundary decoder.
+ */
+export const collectRegistry = (
+  registry: Registry,
+  compileInputSchema: (input: object, where: string) => InputSchemaCompilation,
+): RegistryCollection => {
+  const requirementKey = Symbol.for("executor/apps/requirement");
+  const problems = registry.problems.map((problem) => problem.message);
+  const app = registry.app;
+
+  const requirementSpecOf = (value: unknown) =>
+    typeof value === "object" && value !== null && requirementKey in value
+      ? (value as Record<PropertyKey, unknown>)[requirementKey] as {
+          readonly service: {
+            readonly origin: string;
+            readonly auth?: Readonly<Record<string, unknown>>;
+          };
+          readonly arity: "one" | "optional" | "many";
+          readonly grant?: string;
+          readonly description?: string;
+        }
+      : undefined;
+
+  const canonicalJson = (value: unknown): string => {
+    const sortKeys = (node: unknown): unknown => {
+      if (Array.isArray(node)) return node.map(sortKeys);
+      if (typeof node === "object" && node !== null)
+        return Object.fromEntries(
+          Object.entries(node as Record<string, unknown>)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, child]) => [key, sortKeys(child)]),
+        );
+      return node;
+    };
+    return JSON.stringify(sortKeys(value));
+  };
+
+  const claims = new Map<string, CollectedClaim>();
+  for (const [origin, registered] of registry.services) {
+    if (registered.file !== "app.ts") continue;
+    const { decl } = registered;
+    claims.set(origin, {
+      origin,
+      reach: decl.reach ?? [],
+      params: decl.params ?? {},
+      auth: decl.auth ?? {},
+    });
+  }
+
+  const collectRequirement = (
+    role: string,
+    requirement: unknown,
+    where: string,
+  ): CollectedRequirement | undefined => {
+    const spec = requirementSpecOf(requirement);
+    if (spec === undefined) {
+      problems.push(`${where}: requirement '${role}' is not a service/requirement value`);
+      return undefined;
+    }
+    const origin = spec.service.origin;
+    if (!claims.has(origin))
+      problems.push(`${where}: requirement '${role}' names ${origin}, which app.ts does not declare`);
+    if (spec.grant !== undefined && !(spec.grant in (spec.service.auth ?? {})))
+      problems.push(
+        `${where}: requirement '${role}' pins grant '${spec.grant}', not a auth method on ${origin}`,
+      );
+    return {
+      role,
+      service: origin,
+      arity: spec.arity,
+      ...(spec.grant === undefined ? {} : { grant: spec.grant }),
+      ...(spec.description === undefined ? {} : { description: spec.description }),
+    };
+  };
+
+  if (app === undefined) problems.push("app.ts must call defineApp({...})");
+  else if (typeof app.description !== "string" || app.description.trim().length === 0)
+    problems.push("app.ts: app description must not be empty");
+
+  for (const [file, summary] of registry.toolFiles) {
+    if (summary.definitions > 1 && summary.hasUnnamedTool)
+      problems.push(`${file}: multi-tool files must name every tool`);
+  }
+
+  const tools: CollectedTool[] = [];
+  if (app !== undefined) {
+    for (const [name, registered] of registry.tools) {
+      const { spec, file } = registered;
+      const address = `${app.key}/${name}`;
+      if (typeof spec.description !== "string" || spec.description.trim().length === 0)
+        problems.push(`${file}: tool '${name}' description must not be empty`);
+      const requires = Object.entries(spec.requirements ?? {})
+        .flatMap(([role, requirement]) => {
+          const collected = collectRequirement(role, requirement, address);
+          return collected === undefined ? [] : [collected];
+        })
+        .sort((left, right) => left.role.localeCompare(right.role));
+      let compiled: InputSchemaCompilation;
+      try {
+        compiled = compileInputSchema(spec.input, address);
+      } catch (error) {
+        compiled = {
+          problem: `${address}: input schema could not compile to JSON schema (${
+            error instanceof Error ? error.message : String(error)
+          })`,
+        };
+      }
+      if ("problem" in compiled) {
+        problems.push(compiled.problem);
+        continue;
+      }
+      tools.push({
+        address,
+        name,
+        description: spec.description,
+        inputSchema: compiled.value,
+        annotations: spec.annotations ?? {},
+        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 appResult = { key: app.key, label: app.label, description: app.description };
+  const manifest = { app: appResult, services, tools: sortedTools } satisfies CollectedManifest;
+  return {
+    problems: [],
+    manifest,
+    canonical: canonicalJson(manifest),
+  };
+};

package/src/manifest/contract.ts

@@ -0,0 +1,55 @@
+import { Data, Schema } from "effect";
+import type { AuthMethod, ParamSpec } from "../authoring/index";
+
+/** A service claim projected from a registered declaration. */
+export interface CollectedClaim {
+  readonly origin: string;
+  readonly reach: readonly string[];
+  readonly params: Readonly<Record<string, ParamSpec>>;
+  readonly auth: Readonly<Record<string, AuthMethod>>;
+}
+
+/** A tool requirement projected from an authoring value. */
+export interface CollectedRequirement {
+  readonly role: string;
+  readonly service: string;
+  readonly arity: "one" | "optional" | "many";
+  readonly grant?: string;
+  readonly description?: string;
+}
+
+/** JSON object accepted for a persisted tool input schema. */
+export const JsonSchemaObject = Schema.Record(Schema.String, Schema.Json);
+export type JsonSchemaObject = typeof JsonSchemaObject.Type;
+
+/** A validated, publishable tool row. */
+export interface ManifestTool {
+  readonly address: string;
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: JsonSchemaObject;
+  readonly annotations: {
+    readonly readOnly?: boolean;
+    readonly destructive?: boolean;
+    readonly scopes?: readonly 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[];
+}
+
+/** All publish-time authoring problems from one registry load. */
+export class PublishError extends Data.TaggedError("PublishError")<{
+  readonly problems: readonly string[];
+}> {
+  override get message(): string {
+    return `publish failed:\n${this.problems.map((problem) => `  - ${problem}`).join("\n")}`;
+  }
+}