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

package/src/runner/protocol.ts

@@ -1,20 +1,26 @@
-import { Crypto, Data, type Effect, FileSystem } from "effect";
+import { Data, type Effect, FileSystem } from "effect";
 import type { AppManifestResult, PublishError } from "../manifest/contract";
+import type {
+  CallFailureKind,
+  DiscoveredTool,
+  ToolCtx,
+  ToolCtxEntry,
+} from "../runtime/index";
 
-/** The capability exposed to one tool requirement role. */
-export interface ToolCtxEntry {
-  readonly grant: string;
-  readonly token?: string;
-  readonly secrets?: Readonly<Record<string, string>>;
-  fetch(path: string, init?: RequestInit): Promise<Response>;
-}
+export type {
+  DiscoveredTool,
+  ToolCtx,
+  ToolCtxEntry,
+  ToolDescriptor,
+} from "../runtime/index";
 
-/** Tool capabilities keyed by requirement role. */
-export type ToolCtx = Readonly<Record<string, ToolCtxEntry>>;
+/** Which invocation phase failed. */
+export type CallErrorKind = CallFailureKind;
 
-/** A runner operation failure associated with its target. */
+/** 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 {
@@ -22,20 +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,
-    Crypto.Crypto | FileSystem.FileSystem
-  >;
+  manifest(): Effect.Effect<AppManifestResult, PublishError, FileSystem.FileSystem>;
   call(
-    name: string,
+    address: string,
     input: unknown,
     ctx: ToolCtx,
-  ): Effect.Effect<unknown, CallError, Crypto.Crypto | FileSystem.FileSystem>;
+    detail?: unknown,
+  ): Effect.Effect<unknown, CallError, FileSystem.FileSystem>;
   discover(
-    name: string,
-    binding: unknown,
-  ): Effect.Effect<unknown, CallError, Crypto.Crypto | FileSystem.FileSystem>;
+    segment: string,
+    ctx: ToolCtx,
+  ): Effect.Effect<readonly DiscoveredTool[], DiscoverError, FileSystem.FileSystem>;
 }

package/src/runtime/index.ts

@@ -0,0 +1,550 @@
+/**
+ * The execution core: everything that happens after authored modules
+ * load, in any environment. Project a registry into its deterministic
+ * manifest, validate a call's input, run the handler, shape the
+ * outcome. There is exactly one implementation of this logic; the
+ * local runner and the sandboxed workerd guest are both thin doors
+ * onto this module.
+ *
+ * Deliberately dependency-free (no effect, no node builtins): this
+ * module bundles into sandboxed guests, where every dependency is
+ * paid on each cold start. Digesting uses WebCrypto, which node, bun,
+ * and workerd all provide.
+ */
+
+import type {
+  DiscoveredToolSpec,
+  DynamicToolsSpec,
+  Registry,
+} from "../authoring/index";
+import type {
+  AppManifestResult,
+  CollectedClaim,
+  CollectedRequirement,
+  JsonSchemaObject,
+  ManifestDynamic,
+  ManifestTool,
+} from "../manifest/contract";
+
+// ── tool capabilities ─────────────────────────────────────────────────
+
+/** 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>;
+}
+
+/** Tool capabilities keyed by requirement role. */
+export type ToolCtx = Readonly<Record<string, ToolCtxEntry>>;
+
+// ── outcomes ──────────────────────────────────────────────────────────
+
+/** A manifest projection: the app's deterministic description, or why not. */
+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 = (kind: CallFailureKind, reason: string): CallOutcome => ({
+  ok: false,
+  kind,
+  reason,
+});
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+// ── input schema compilation ──────────────────────────────────────────
+
+type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+const isJsonValue = (value: unknown): value is JsonValue => {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(isJsonValue);
+  if (typeof value !== "object") return false;
+  return Object.values(value).every(isJsonValue);
+};
+
+interface StandardJsonSchemaCapable {
+  readonly "~standard": {
+    readonly jsonSchema?: {
+      readonly input: (options: { readonly target: string }) => unknown;
+    };
+  };
+}
+
+const standardJsonSchemaOf = (input: object) =>
+  "~standard" in input
+    ? (input as StandardJsonSchemaCapable)["~standard"].jsonSchema
+    : undefined;
+
+/** Strict-by-default: authored schemas reject unknown keys unless stated. */
+const strictify = (node: unknown): unknown => {
+  if (typeof node !== "object" || node === null) return node;
+  if (Array.isArray(node)) return node.map(strictify);
+  const object = { ...(node as Record<string, unknown>) };
+  if (object.type === "object" && object.additionalProperties === undefined)
+    object.additionalProperties = false;
+  for (const key of ["items", "anyOf", "oneOf", "allOf"])
+    if (key in object) object[key] = strictify(object[key]);
+  for (const key of ["properties", "$defs"])
+    if (object[key] !== undefined && typeof object[key] === "object" && object[key] !== null)
+      object[key] = Object.fromEntries(
+        Object.entries(object[key] as Record<string, unknown>).map(([name, value]) => [
+          name,
+          strictify(value),
+        ]),
+      );
+  return object;
+};
+
+type InputSchemaCompilation =
+  | { readonly value: JsonSchemaObject }
+  | { readonly problem: string };
+
+export const compileInputSchema = (input: object, where: string): InputSchemaCompilation => {
+  const standard = standardJsonSchemaOf(input);
+  if ("~standard" in input && typeof standard?.input !== "function")
+    return {
+      problem: `${where}: input is a Standard Schema without the jsonSchema extension — use a library that implements it (zod 4+, effect Schema) or pass raw JSON schema`,
+    };
+  try {
+    const compiled = strictify(
+      typeof standard?.input === "function"
+        ? standard.input({ target: "draft-2020-12" })
+        : structuredClone(input),
+    );
+    if (
+      typeof compiled !== "object" ||
+      compiled === null ||
+      Array.isArray(compiled) ||
+      !isJsonValue(compiled)
+    )
+      throw new Error("expected a JSON object");
+    return { value: compiled as JsonSchemaObject };
+  } catch (error) {
+    return {
+      problem: `${where}: input schema could not compile to JSON schema (${errorMessage(error)})`,
+    };
+  }
+};
+
+// ── registry projection ───────────────────────────────────────────────
+
+const requirementKey = Symbol.for("executor/apps/requirement");
+
+interface RequirementSpecShape {
+  readonly service: {
+    readonly origin: string;
+    readonly auth?: Readonly<Record<string, unknown>>;
+  };
+  readonly arity: "one" | "optional" | "many";
+  readonly grant?: string;
+  readonly description?: string;
+}
+
+const requirementSpecOf = (value: unknown): RequirementSpecShape | undefined =>
+  typeof value === "object" && value !== null && requirementKey in value
+    ? ((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);
+    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));
+};
+
+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 =
+  | { readonly problems: readonly string[] }
+  | {
+      readonly problems: readonly [];
+      readonly manifest: CollectedManifest;
+      readonly canonical: string;
+    };
+
+const collectRegistry = (registry: Registry): RegistryCollection => {
+  const problems = registry.problems.map((problem) => problem.message);
+  const app = registry.app;
+
+  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`);
+    if (registry.dynamic.has(file))
+      problems.push(`${file}: a file claims a dynamic tool set or defines tools, never both`);
+  }
+
+  const tools: ManifestTool[] = [];
+  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));
+      const compiled = compileInputSchema(spec.input, address);
+      if ("problem" in compiled) {
+        problems.push(compiled.problem);
+        continue;
+      }
+      tools.push({
+        address,
+        name,
+        description: spec.description,
+        inputSchema: compiled.value,
+        annotations: spec.annotations ?? {},
+        requires,
+        file,
+      });
+    }
+  }
+
+  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,
+    dynamic: sortedDynamic,
+  } satisfies CollectedManifest;
+  return { problems: [], manifest, canonical: canonicalJson(manifest) };
+};
+
+const digestOf = async (canonical: string): Promise<string> => {
+  const bytes = new Uint8Array(
+    await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical)),
+  );
+  return Array.from(bytes.slice(0, 8), (byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+
+/** Project a loaded registry into the app's deterministic manifest. */
+export const manifestOf = async (registry: Registry): Promise<ManifestOutcome> => {
+  const collected = collectRegistry(registry);
+  if (collected.problems.length > 0) return { ok: false, problems: collected.problems };
+  if (!("manifest" in collected))
+    return { ok: false, problems: ["validated registry projection unexpectedly missing"] };
+  return {
+    ok: true,
+    result: { digest: `snap:${await digestOf(collected.canonical)}`, ...collected.manifest },
+  };
+};
+
+// ── invocation ────────────────────────────────────────────────────────
+
+interface StandardValidateCapable {
+  readonly "~standard": {
+    readonly validate: (value: unknown) =>
+      | { readonly value: unknown; readonly issues?: undefined }
+      | { readonly issues: ReadonlyArray<{ readonly message: string }> }
+      | Promise<
+          | { readonly value: unknown; readonly issues?: undefined }
+          | { readonly issues: ReadonlyArray<{ readonly message: string }> }
+        >;
+  };
+}
+
+const standardValidateOf = (input: object) =>
+  "~standard" in input &&
+  typeof (input as StandardValidateCapable)["~standard"].validate === "function"
+    ? (input as StandardValidateCapable)["~standard"].validate
+    : undefined;
+
+type ParsedInput =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly reason: string };
+
+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 {
+    const result = await validate(input);
+    if (result.issues !== undefined)
+      return {
+        ok: false,
+        reason: `invalid input (${result.issues.map((issue) => issue.message).join("; ")})`,
+      };
+    return { ok: true, value: result.value };
+  } catch (error) {
+    return { ok: false, reason: `input validation threw (${errorMessage(error)})` };
+  }
+};
+
+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,
+  address: string,
+  input: unknown,
+  ctx: ToolCtx,
+  detail?: unknown,
+): Promise<CallOutcome> => {
+  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 {
+    const call = pair.call as (
+      tool: { readonly name: string; readonly detail: unknown },
+      value: unknown,
+      toolCtx: ToolCtx,
+    ) => Promise<unknown>;
+    return {
+      ok: true,
+      value: await call({ name: dynamic.name, detail }, parsed.value, ctx),
+    };
+  } catch (error) {
+    return failure("handler", `dynamic call failed (${errorMessage(error)})`);
+  }
+};
+
+/** Discover and compile one dynamic segment. */
+export const discoverTool = async (
+  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

@@ -1,2 +1,17 @@
-/** Worker-safe registry projection injected into sandboxed app workers. @internal */
-export { collectRegistry } from "../manifest/collect";
+/**
+ * The execution core re-exported for sandboxed guests. A generated
+ * guest module imports the authored files (filling the registry) and
+ * exposes these verbs over RPC; the logic itself lives in ../runtime
+ * and is identical to what the local runner executes. @internal
+ */
+export {
+  callTool,
+  discoverTool,
+  manifestOf,
+  type CallOutcome,
+  type DiscoverOutcome,
+  type DiscoveredTool,
+  type ManifestOutcome,
+  type ToolCtx,
+  type ToolCtxEntry,
+} from "../runtime/index";