apps 1.0.0-beta.1 → 1.0.0-beta.2

package/src/runtime/index.ts

@@ -0,0 +1,363 @@
+/**
+ * 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 { Registry, ToolSpec } from "../authoring/index";
+import type {
+  AppManifestResult,
+  CollectedClaim,
+  CollectedRequirement,
+  JsonSchemaObject,
+  ManifestTool,
+} from "../manifest/contract";
+
+// ── tool capabilities ─────────────────────────────────────────────────
+
+/** 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>;
+}
+
+/** 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[] };
+
+/** One tool invocation's result envelope. */
+export type CallOutcome =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly reason: string };
+
+const failure = (reason: string): CallOutcome => ({ ok: false, 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 };
+
+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 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[];
+}
+
+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`);
+  }
+
+  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,
+      });
+    }
+  }
+
+  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) };
+};
+
+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 (spec: ToolSpec, input: unknown): Promise<ParsedInput> => {
+  const validate = standardValidateOf(spec.input);
+  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)})` };
+  }
+};
+
+/** Validate input and run one registered tool's handler. */
+export const callTool = async (
+  registry: Registry,
+  name: string,
+  input: unknown,
+  ctx: ToolCtx,
+): 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;
+  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 failed (${errorMessage(error)})`);
+  }
+};
+
+/** Discover one dynamic tool set's current segment. Unbuilt: always fails. */
+export const discoverTool = async (
+  _registry: Registry,
+  _name: string,
+  _binding: unknown,
+): Promise<CallOutcome> => failure("no dynamic tools yet");

package/src/workerd/index.ts

@@ -1,2 +1,15 @@
-/** 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 ManifestOutcome,
+  type ToolCtx,
+  type ToolCtxEntry,
+} from "../runtime/index";

package/dist/chunk-J5AVXTHA.js

@@ -1,154 +0,0 @@
-import {
-  __enterFile,
-  __leaveFile,
-  newRegistry,
-  setActiveRegistry
-} from "./chunk-LWKQDDLZ.js";
-import {
-  JsonSchemaObject,
-  PublishError
-} from "./chunk-B7NEUIJL.js";
-import {
-  collectRegistry
-} from "./chunk-RZA7AXBK.js";
-
-// src/manifest/index.ts
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { Crypto, Effect, FileSystem, Schema, Semaphore } from "effect";
-var hasStandardJsonSchema = (input) => "~standard" in input && typeof input["~standard"].jsonSchema?.input === "function";
-var compileInputSchema = (input, where) => {
-  if ("~standard" in input) {
-    if (!hasStandardJsonSchema(input))
-      return {
-        problem: `${where}: input is a Standard Schema without the jsonSchema extension \u2014 use a library that implements it (zod 4+, effect Schema) or pass raw JSON schema`
-      };
-  }
-  try {
-    const compiled = strictify(
-      hasStandardJsonSchema(input) ? input["~standard"].jsonSchema.input({ target: "draft-2020-12" }) : structuredClone(input)
-    );
-    return { value: Schema.decodeUnknownSync(JsonSchemaObject)(compiled) };
-  } catch (error) {
-    return { problem: schemaPublishProblem(where, error) };
-  }
-};
-var schemaPublishProblem = (where, error) => `${where}: input schema could not compile to JSON schema (${error instanceof Error ? error.message : String(error)})`;
-var strictify = (node) => {
-  if (typeof node !== "object" || node === null) return node;
-  if (Array.isArray(node)) return node.map(strictify);
-  const object = { ...node };
-  if (object.type === "object" && object.additionalProperties === void 0)
-    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] !== void 0 && typeof object[key] === "object" && object[key] !== null)
-      object[key] = Object.fromEntries(
-        Object.entries(object[key]).map(([name, value]) => [
-          name,
-          strictify(value)
-        ])
-      );
-  return object;
-};
-var digestOf = (content) => Effect.gen(function* () {
-  const crypto = yield* Crypto.Crypto;
-  const bytes = yield* Effect.orDie(
-    crypto.digest("SHA-256", new TextEncoder().encode(content))
-  );
-  return Array.from(bytes.slice(0, 8), (byte) => byte.toString(16).padStart(2, "0")).join("");
-});
-var loadPermit = Semaphore.makeUnsafe(1);
-var runNonce = 0;
-var baseAppImports = /* @__PURE__ */ new Set();
-var moduleFailure = (where, error) => new PublishError({
-  problems: [
-    `${where}: failed to execute (${error instanceof Error ? error.message : String(error)})`
-  ]
-});
-var canonicalModuleUrl = (path, where) => Effect.gen(function* () {
-  const fs = yield* FileSystem.FileSystem;
-  const realPath = yield* fs.realPath(path).pipe(
-    Effect.mapError((error) => moduleFailure(where, error))
-  );
-  return pathToFileURL(realPath);
-});
-var importModule = (specifier, where) => Effect.tryPromise({
-  try: () => import(specifier).then(() => void 0),
-  catch: (error) => moduleFailure(where, error)
-});
-var recordModuleProblems = (registry, effect) => effect.pipe(
-  Effect.catchTag(
-    "PublishError",
-    (error) => Effect.sync(() => {
-      registry.problems.push(...error.problems.map((message) => ({ message })));
-    })
-  )
-);
-var executeModules = (appDir, files) => loadPermit.withPermit(
-  Effect.uninterruptibleMask(
-    (restore) => Effect.gen(function* () {
-      const registry = newRegistry();
-      const previous = yield* Effect.sync(() => setActiveRegistry(registry));
-      const nonce = yield* Effect.sync(() => ++runNonce);
-      const execute = Effect.gen(function* () {
-        __enterFile("app.ts");
-        yield* recordModuleProblems(
-          registry,
-          Effect.gen(function* () {
-            const appUrl = yield* canonicalModuleUrl(`${appDir}/app.ts`, "app.ts");
-            const baseUrl = appUrl.href;
-            const specifier = baseAppImports.has(baseUrl) ? `${fileURLToPath(appUrl)}?m=${nonce}` : baseUrl;
-            yield* importModule(specifier, "app.ts");
-            yield* Effect.sync(() => baseAppImports.add(baseUrl));
-          })
-        );
-        for (const file of files) {
-          const where = `tools/${file}`;
-          __enterFile(where);
-          yield* recordModuleProblems(
-            registry,
-            Effect.gen(function* () {
-              const url = yield* canonicalModuleUrl(`${appDir}/tools/${file}`, where);
-              yield* importModule(`${fileURLToPath(url)}?m=${nonce}`, where);
-            })
-          );
-        }
-      });
-      yield* restore(execute).pipe(
-        Effect.ensuring(
-          Effect.sync(() => {
-            __leaveFile();
-            setActiveRegistry(previous);
-          })
-        )
-      );
-      return registry;
-    })
-  )
-);
-var loadApp = (appDir) => Effect.gen(function* () {
-  const fs = yield* FileSystem.FileSystem;
-  const files = (yield* fs.readDirectory(`${appDir}/tools`).pipe(
-    Effect.mapError((error) => new PublishError({ problems: [`tools/: ${error.message}`] }))
-  )).filter((file) => file.endsWith(".ts")).sort();
-  const registry = yield* executeModules(appDir, files);
-  const collected = collectRegistry(registry, compileInputSchema);
-  if (collected.problems.length > 0)
-    return yield* new PublishError({ problems: collected.problems });
-  if (!("manifest" in collected))
-    return yield* Effect.die("validated registry projection unexpectedly missing");
-  return {
-    registry,
-    result: {
-      digest: `snap:${yield* digestOf(collected.canonical)}`,
-      ...collected.manifest
-    }
-  };
-});
-var manifest = (appDir) => Effect.map(loadApp(appDir), ({ result }) => result);
-
-export {
-  loadApp,
-  manifest
-};

package/dist/chunk-RZA7AXBK.js

@@ -1,107 +0,0 @@
-// src/manifest/collect.ts
-var collectRegistry = (registry, compileInputSchema) => {
-  const requirementKey = Symbol.for("executor/apps/requirement");
-  const problems = registry.problems.map((problem) => problem.message);
-  const app = registry.app;
-  const requirementSpecOf = (value) => typeof value === "object" && value !== null && requirementKey in value ? value[requirementKey] : void 0;
-  const canonicalJson = (value) => {
-    const sortKeys = (node) => {
-      if (Array.isArray(node)) return node.map(sortKeys);
-      if (typeof node === "object" && node !== null)
-        return Object.fromEntries(
-          Object.entries(node).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, sortKeys(child)])
-        );
-      return node;
-    };
-    return JSON.stringify(sortKeys(value));
-  };
-  const claims = /* @__PURE__ */ new Map();
-  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, requirement, where) => {
-    const spec = requirementSpecOf(requirement);
-    if (spec === void 0) {
-      problems.push(`${where}: requirement '${role}' is not a service/requirement value`);
-      return void 0;
-    }
-    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 !== void 0 && !(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 === void 0 ? {} : { grant: spec.grant },
-      ...spec.description === void 0 ? {} : { description: spec.description }
-    };
-  };
-  if (app === void 0) 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 = [];
-  if (app !== void 0) {
-    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 === void 0 ? [] : [collected];
-      }).sort((left, right) => left.role.localeCompare(right.role));
-      let compiled;
-      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 === void 0) 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 };
-  return {
-    problems: [],
-    manifest,
-    canonical: canonicalJson(manifest)
-  };
-};
-
-export {
-  collectRegistry
-};