apps 0.0.1-beta.0 → 0.0.1-beta.10

package/README.md

@@ -11,22 +11,22 @@ For local testing, install the tarball made by `bun run pack` in this directory.
 
 ```ts
 import { defineApp } from "apps";
-import { mcpOperations } from "apps/mcp";
+import { mcpRouter } from "apps/mcp";
 
 export default defineApp({ accounts: {} }, async ({ signal }) => ({
-  ...(await mcpOperations({
+  tools: await mcpRouter({
     url: "https://mcp.deepwiki.com/mcp",
     ...(signal === undefined ? {} : { signal }),
-  })),
+  }),
 }));
 ```
 
-| Import           | Helper              | App dependency              |
-| ---------------- | ------------------- | --------------------------- |
-| `apps/mcp`       | `mcpOperations`     | `@modelcontextprotocol/sdk` |
-| `apps/mcp/stdio` | `stdioOperations`   | `@modelcontextprotocol/sdk` |
-| `apps/graphql`   | `graphqlOperations` | `graphql`                   |
-| `apps/openapi`   | `openapiOperations` | None                        |
+| Import           | Helper          | App dependency              |
+| ---------------- | --------------- | --------------------------- |
+| `apps/mcp`       | `mcpRouter`     | `@modelcontextprotocol/sdk` |
+| `apps/mcp/stdio` | `stdioRouter`   | `@modelcontextprotocol/sdk` |
+| `apps/graphql`   | `graphqlRouter` | `graphql`                   |
+| `apps/openapi`   | `openapiRouter` | None                        |
 
 MCP and GraphQL are optional peers. Subpath imports isolate their module graphs;
 optional peers keep unused libraries out of the dependency installation. The
@@ -43,34 +43,58 @@ Declare the needed peer in the deployed app's `package.json`, for example:
 ```
 
 Product runtimes compile authored source and declared dependencies inside workerd,
-then retain the executable Worker modules. Declare `apps` in `package.json` to
-select its npm version for both server and browser code. Use an exact version to
-keep rebuilds repeatable. Apps with no `apps` dependency use the host's framework.
+then retain the executable Worker modules. Every app declares the exact `apps`
+version in `package.json`; it selects the framework for both server and browser
+code and keeps rebuilds repeatable. A build without it fails and names the
+version the host ships.
 In this repository, playground workspaces use `"apps": "workspace:*"` for development;
 replace that workspace reference with a released version before deployment.
 
-`openapiOperations` accepts normalized operations from the template generator,
-credential placement metadata, and an optional selected account. It does not
-parse a raw OpenAPI specification. `packages/app-templates` owns that compiler.
-No extra OpenAPI parser is installed in the app.
-
-Authenticated templates use `provider.many()` and `accountOperations` from `apps`:
+`liveOpenapiRouter` reads an OpenAPI document through `ctx.cache`. Generated
+imports retain a source URL, allowed origin, and static credential bindings in
+`openapi.json`. The framework compiles a revision on a cache miss. It writes each
+operation and shared schema before publishing the current revision. A warm call
+reads that revision and the requested operation's schema dependencies. It does
+not download, parse, or read the full catalog. `openapiRouter` remains the
+lower-level helper for already normalized metadata.
+`parameterDefaults` binds path, query or header values to the selected account.
+Those parameters become optional and publish their value as the schema `default`;
+an explicit value still wins.
+
+The default refresh window is five minutes fresh plus five minutes stale.
+`freshFor` and `staleFor` can change it. A stale read schedules a bounded refresh;
+a failed refresh keeps the last successful revision until its stale window ends.
+The source URL and static compilation configuration identify a shared source.
+Accounts bind at execution time. Live documents cannot change credential
+placement or send credentials to another origin. Editing generated source and
+redeploying is required to change those static choices.
+
+Authenticated templates use `provider.many()` and `accountRouter` from `apps`:
 
 ```ts
-export default defineApp({ accounts: { service: provider.many() } }, async ({ accounts, signal }) =>
-  accountOperations(
-    accounts.service,
-    (account) =>
-      mcpOperations({
-        url: "https://example.com/mcp",
-        headers: { Authorization: "Bearer " + account.fields.token },
-        signal,
-      }),
-    { signal },
-  ),
+export default defineApp(
+  { accounts: { service: provider.many() } },
+  async ({ accounts, signal }) => ({
+    tools: await accountRouter(
+      accounts.service,
+      (account) =>
+        mcpRouter({
+          url: "https://example.com/mcp",
+          headers: { Authorization: "Bearer " + account.fields.token },
+          signal,
+        }),
+      { signal },
+    ),
+  }),
 );
 ```
 
+MCP and GraphQL helpers accept `cache: ctx.cache.forAccount(account)` (or
+`ctx.cache` for a public source). They return a dynamic router, cache remote
+metadata, and compile only the selected tool. The defaults are five minutes fresh
+plus five minutes stale. Use `freshFor` / `staleFor` to change the windows, or
+`revalidate: true` to await a refresh. Tool results are never cached.
+
 Each combined tool takes `{ accountId, input }`. `input` keeps the upstream shape;
 `accountId` must identify a selected account that exposes that tool. Discovery
 and validation remain specific to each account. An empty selection returns no
@@ -151,7 +175,7 @@ and [hosting notes](../../notes/app-ui.md).
 
 ## Webhooks
 
-Expose `webhooks: { issueOpened }` beside queries and mutations. Each definition
+Expose `webhooks: { issueOpened }` beside `tools`. Each definition
 has an `account` requirement, `config` and `state` schemas, and async `register`,
 `handle`, and `unregister` callbacks. Register and unregister must be idempotent;
 handle must verify the provider signature before acting.
@@ -189,3 +213,94 @@ Local and self-host products run authored apps in Alchemy/workerd, using the
 same Worker build format and app-data facets as Cloud. Host filesystem and
 subprocess access are unavailable to app code. Agent `execute(code)` continues
 to use OpenCode CodeMode.
+
+## App cache and lazy sources
+
+Every app context has `cache`. Keys must contain every input that changes the
+result. The host adds app and build isolation. Use `forAccount(account)` for
+private data; it also includes the current credential fingerprint. Use the
+shared cache for public metadata that is identical across accounts.
+
+```ts
+const projects = await ctx.cache.forAccount(ctx.accounts.service).get({
+  key: ["projects", region],
+  schema: array(object({ id: string(), name: string() })),
+  freshFor: "1 minute",
+  staleFor: "2 minutes",
+  load: async ({ fetch, signal }) => {
+    const response = await fetch(urlFor(region), { signal });
+    if (!response.ok) throw new Error("Project lookup failed");
+    return response.json();
+  },
+});
+```
+
+Use the loader's `fetch`, `signal`, and `cache` for background work. Their
+lifetime can outlast the original request. Only successful, schema-valid JSON
+is stored. Concurrent misses share a fenced lease. `invalidate(key)` revokes
+both a cached value and an in-flight loader's right to publish it. Cache storage
+is disposable and bounded: 2 MB per entry, 8 MB per write batch, 128 entries per
+batch, 128 MB and 100,000 entries per app, and seven days of retention. Capacity
+errors are explicit. Background refreshes have a 30-second deadline.
+
+`read` and `readMany` read retained data without loading it. `write` stores
+bounded JSON batches with a retention duration. These support immutable pieces
+that must be stored before a manifest becomes visible.
+
+## Routers
+
+An app's `tools` is a router. Keys form tool paths, and routers nest like tRPC's:
+`router({ health, issues: router({ list, close }, { description }) })` exposes
+`health`, `issues.list` and `issues.close`. Each query or mutation keeps its own
+kind; names carry no `queries.` or `mutations.` prefix. Router options are
+`title`, `description`, `instructions`, `icons` and `tags`. Instructions become a
+skill named `tools` for the root router and `tools-<path>` below it, such as
+`tools-issues`. Paths other than lowercase letters and digits get a slug and a
+hash of the path, so names never collide. An authored skill with the same name
+replaces the generated one. `router(source, options)` overrides a source's
+metadata. Keys `__proto__`, `constructor` and `prototype` are reserved, and an
+mutation can be mounted at only one path.
+
+Protocol helpers return routers, so an app mounts several sources under keys.
+`mcpRouter` takes its title, description, icons and instructions from the
+server, and `liveOpenapiRouter` from the document's `info` and tags. `stdioRouter`,
+`openapiRouter` and `graphqlRouter` carry no source metadata. A nested router that fails to load is reported on its own catalog entry;
+the app's other tools still load. The root failing fails discovery.
+
+`dynamicRouter({ list, resolve })` separates descriptions from executable
+operations. `list()` returns tool metadata with names relative to the router,
+such as `getProject`; names may contain dots. `resolve(name)` returns a
+query/mutation declaration or `undefined`. The host validates input and applies
+approval policy after resolving an operation. `accountRouter` preserves this
+separation. Static operations run without resolving a source; listings reject
+duplicate names.
+
+```ts
+export default defineApp(
+  { accounts: {} },
+  {
+    tools: dynamicRouter({
+      list: async () => [
+        {
+          name: "ping",
+          description: "Return pong",
+          inputSchema: { type: "object", properties: {} },
+          readOnly: true,
+        },
+      ],
+      resolve: async (name) =>
+        name === "ping" ? query({ input: object({}) }, async () => "pong") : undefined,
+    }),
+  },
+);
+```
+
+Mark queries with `readOnly: true`; other listed tools are mutations. `list`
+describes available tools; `resolve` returns the matching declaration. An
+optional `meta()` returns the router's title, description and instructions.
+
+`ctx.cache.revalidate(options)` takes the same options as `get`, but always
+awaits a refresh. Concurrent refreshes share a load. The previous value stays
+available to ordinary readers while refresh runs, and a failed refresh does not
+remove it. Use this at an explicit connection or user refresh boundary; it is
+not a reason to refresh on every tool call.