@reboot-dev/reboot 0.44.0 → 0.45.1

package/README.md

@@ -0,0 +1,160 @@
+<div align="center">
+
+<img src="https://docs.reboot.dev/img/reboot-logo-green.svg"
+     alt="Reboot" width="200" />
+
+# Reboot
+
+**Build AI Chat Apps — and full-stack web apps — with reactive, durable backends.**
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/reboot)](https://pypi.org/project/reboot/)
+[![npm](https://img.shields.io/npm/v/@reboot-dev/reboot)](https://www.npmjs.com/package/@reboot-dev/reboot)
+[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/cRbdcS94Nr)
+[![Docs](https://img.shields.io/badge/docs-reboot.dev-green)](https://docs.reboot.dev/)
+
+</div>
+
+---
+
+Reboot is a framework for building **reactive, stateful, multiplayer AI chat
+apps** — visual apps that run inside ChatGPT, Claude, VS Code, Goose, and more.
+It also builds full-stack web apps with reactive backends and React frontends.
+
+With Reboot, you just write business logic — no wiring up databases, caches,
+queues, or retry loops. State survives failures by default. ACID transactions
+span multiple states. The React frontend stays in sync in real time. And your
+backend is automatically an MCP server.
+
+## AI Chat Apps
+
+Build visual, interactive apps that run inside AI chat interfaces. Define a
+`Session` type as an entry point and your methods automatically become tools
+the AI can call:
+
+```python
+from reboot.api import (
+    API, Field, Methods, Model, Reader, Tool,
+    Transaction, Type, UI, Writer,
+)
+
+
+class CreateCounterResponse(Model):
+    counter_id: str = Field(tag=1)
+
+
+class SessionState(Model):
+    pass
+
+
+class CounterState(Model):
+    value: int = Field(tag=1, default=0)
+
+
+class GetResponse(Model):
+    value: int = Field(tag=1)
+
+
+class IncrementRequest(Model):
+    """Request with an amount parameter."""
+    amount: int | None = Field(tag=1, default=None)
+
+
+api = API(
+    Session=Type(
+        state=SessionState,
+        methods=Methods(
+            create_counter=Transaction(
+                request=None,
+                response=CreateCounterResponse,
+                description="Create a new Counter.",
+            ),
+        ),
+    ),
+    Counter=Type(
+        state=CounterState,
+        methods=Methods(
+            show_clicker=UI(
+                request=None,
+                path="web/ui/clicker",
+                title="Counter Clicker",
+                description="Interactive clicker UI.",
+            ),
+            create=Writer(
+                request=None,
+                response=None,
+                factory=True,
+            ),
+            get=Reader(
+                request=None,
+                response=GetResponse,
+                description="Get the current counter "
+                "value.",
+                mcp=Tool(),
+            ),
+            increment=Writer(
+                request=IncrementRequest,
+                response=None,
+                description="Increment the counter.",
+                mcp=Tool(),
+            ),
+        ),
+    ),
+)
+```
+
+### Dive in!
+
+- [What is an AI Chat App?](https://docs.reboot.dev/ai_chat_apps/what_is)
+- [Get Started (Python)](https://docs.reboot.dev/ai_chat_apps/get_started)
+- [AI Chat App Examples](https://docs.reboot.dev/ai_chat_apps/examples)
+
+## Full-stack apps
+
+Build reactive backends with React frontends — great as a full-page extension
+of your AI chat app, or as a standalone web app.
+
+- [TypeScript Quickstart](https://docs.reboot.dev/full_stack_apps/typescript)
+- [Python Quickstart](https://docs.reboot.dev/full_stack_apps/python)
+- [Full-stack Examples](https://docs.reboot.dev/full_stack_apps/examples)
+
+## Key features
+
+**Automatic MCP server.** `Session` methods are automatically exposed as
+MCP tools. Other types can opt in with `mcp=Tool()`. `UI` methods open
+React apps in the AI's chat. No glue code.
+
+**Durable state by default.** States survive process crashes, deployments, and
+chaos. No external database required.
+
+**ACID transactions across states.** `transaction` methods compose atomically
+across many state instances running on different machines.
+
+**Reactive React frontend.** Generated hooks keep your UI in sync
+without manual management of WebSockets, caches, or polling.
+
+**Method system.** Code is safer to write (and _read_) with a clear API
+and methods with enforced constraints: `reader` (concurrent, read-only),
+`writer` (serialized, mutating), `transaction` (ACID, cross-state),
+`workflow` (long-running, durable, cancellable), `ui` (React app in AI
+chat). The runtime enforces these guarantees.
+
+**API-first, code-generated.** Define APIs using Pydantic (Python) or
+Zod (TypeScript). Reboot generates type-safe client, server, and React
+stubs.
+
+## Documentation
+
+Full documentation at [docs.reboot.dev](https://docs.reboot.dev/).
+
+## Community
+
+- **Discord**: [discord.gg/cRbdcS94Nr](https://discord.gg/cRbdcS94Nr) — fastest way to get help or share what you're building
+- **Issues**: [github.com/reboot-dev/reboot/issues](https://github.com/reboot-dev/reboot/issues)
+
+Contributions are welcome. Open an issue to discuss substantial changes before
+sending a pull request.
+
+## License
+
+[Apache 2.0](LICENSE)

package/index.d.ts

@@ -60,7 +60,8 @@ export declare class Context {
     readonly cookie: string | null;
     readonly appInternal: boolean;
     readonly auth: Auth | null;
-    constructor({ external, stateId, method, stateTypeName, callerBearerToken, cookie, appInternal, auth, cancelled, }: {
+    readonly workflowId: string | null;
+    constructor({ external, stateId, method, stateTypeName, callerBearerToken, cookie, appInternal, auth, workflowId, cancelled, }: {
         external: any;
         stateId: string;
         method: string;
@@ -69,6 +70,7 @@ export declare class Context {
         cookie: string | null;
         appInternal: boolean;
         auth: Auth | null;
+        workflowId: string | null;
         cancelled: Promise<void>;
     });
     static fromNativeExternal({ kind, ...options }: {
@@ -101,6 +103,10 @@ export type Interval = {
 export declare class WorkflowContext extends Context {
     #private;
     constructor(options: any);
+    makeIdempotencyKey({ alias, perWorkflow, }: {
+        alias: string;
+        perWorkflow?: boolean;
+    }): string;
     loop(alias: string, { interval }?: {
         interval?: Interval;
     }): AsyncGenerator<number, void, unknown>;
@@ -178,7 +184,7 @@ export declare abstract class Authorizer<StateType, RequestTypes> {
      *         `errors_pb.PermissionDenied()` otherwise.
      */
     abstract authorize(methodName: string, context: ReaderContext, state?: StateType, request?: RequestTypes): Promise<AuthorizerDecision>;
-    _authorize?: (external: any, cancelled: Promise<void>, bytesCall: Uint8Array) => Promise<Uint8Array>;
+    abstract _authorize(external: any, cancelled: Promise<void>, bytesCall: Uint8Array): Promise<Uint8Array>;
 }
 export type AuthorizerCallable<StateType, RequestType> = (args: {
     context: ReaderContext;
@@ -212,15 +218,30 @@ export declare function isAppInternal({ context, }: {
     state?: any;
     request?: any;
 }): errors_pb.PermissionDenied | errors_pb.Ok;
+export type NativeLibrary = {
+    nativeLibraryModule: string;
+    nativeLibraryFunction: string;
+    authorizer?: Authorizer<unknown, unknown>;
+};
+export type TypeScriptLibrary = {
+    name: string;
+    servicers: () => ServicerFactory[];
+    requirements?: () => string[];
+    preRun?: (application: Application) => Promise<void>;
+    initialize?: (context: InitializeContext) => Promise<void>;
+};
+export type Library = TypeScriptLibrary | NativeLibrary;
 export declare class Application {
     #private;
-    constructor({ servicers, initialize, initializeBearerToken, tokenVerifier, }: {
-        servicers: ServicerFactory[];
+    constructor({ servicers, libraries, initialize, initializeBearerToken, tokenVerifier, }: {
+        servicers?: ServicerFactory[];
+        libraries?: Library[];
         initialize?: (context: InitializeContext) => Promise<void>;
         initializeBearerToken?: string;
         tokenVerifier?: TokenVerifier;
     });
     get servicers(): ServicerFactory[];
+    get libraries(): Library[];
     get tokenVerifier(): TokenVerifier;
     get http(): Application.Http;
     run(): Promise<any>;

package/index.js

@@ -9,12 +9,13 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _Reboot_external, _ExternalContext_external, _a, _Context_external, _Context_isInternalConstructing, _ReaderContext_kind, _WriterContext_kind, _TransactionContext_kind, _WorkflowContext_kind, _Application_servicers, _Application_tokenVerifier, _Application_express, _Application_http, _Application_servers, _Application_createExternalContext, _Application_external;
+var _Reboot_external, _ExternalContext_external, _a, _Context_external, _Context_isInternalConstructing, _ReaderContext_kind, _WriterContext_kind, _TransactionContext_kind, _WorkflowContext_kind, _Application_servicers, _Application_libraries, _Application_tokenVerifier, _Application_express, _Application_http, _Application_servers, _Application_createExternalContext, _Application_external;
 import { assert, auth_pb, check_bufbuild_protobuf_library, errors_pb, nodejs_pb, parse, protobuf_es, stringify, tasks_pb, toCamelCase, } from "@reboot-dev/reboot-api";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { fork } from "node:child_process";
 import { createRequire } from "node:module";
 import toobusy from "toobusy-js";
+import { v5 as uuidv5 } from "uuid";
 import { z } from "zod/v4";
 import * as reboot_native from "./reboot_native.cjs";
 import { ensureError } from "./utils/errors.js";
@@ -169,7 +170,7 @@ export async function runWithContext(context, callback) {
     }, callback);
 }
 export class Context {
-    constructor({ external, stateId, method, stateTypeName, callerBearerToken, cookie, appInternal, auth, cancelled, }) {
+    constructor({ external, stateId, method, stateTypeName, callerBearerToken, cookie, appInternal, auth, workflowId, cancelled, }) {
         _Context_external.set(this, void 0);
         if (!__classPrivateFieldGet(_a, _a, "f", _Context_isInternalConstructing)) {
             throw new TypeError("Context is not publicly constructable");
@@ -185,6 +186,7 @@ export class Context {
         this.cookie = cookie;
         this.appInternal = appInternal;
         this.auth = auth;
+        this.workflowId = workflowId;
         this.cancelled = cancelled;
     }
     static fromNativeExternal({ kind, ...options }) {
@@ -263,6 +265,17 @@ export class WorkflowContext extends Context {
         _WorkflowContext_kind.set(this, "workflow");
     }
     // TODO: implement workflow specific properties/methods.
+    makeIdempotencyKey({ alias, perWorkflow, }) {
+        assert(this.workflowId !== null);
+        if (!perWorkflow) {
+            const store = contextStorage.getStore();
+            assert(store !== undefined);
+            if (store.withinLoop) {
+                alias += ` (iteration #${store.loopIteration})`;
+            }
+        }
+        return uuidv5(alias, this.workflowId);
+    }
     async *loop(alias, { interval } = {}) {
         const iterate = await reboot_native.WorkflowContext_loop(this.__external, alias);
         const ms = (interval &&
@@ -384,6 +397,7 @@ export class TokenVerifier {
             cookie: call.context.cookie,
             appInternal: call.context.appInternal,
             auth: null,
+            workflowId: call.context.workflowId !== undefined ? call.context.workflowId : null,
             cancelled,
         });
         const auth = await this.verifyToken(context, call.token);
@@ -506,16 +520,52 @@ export function isAppInternal({ context, }) {
     }
     return new errors_pb.PermissionDenied();
 }
+/**
+ * Prepares libraries for conversion. Wraps `initialize` method for better
+ * error handling.
+ *
+ * @param library Library to be prepared
+ * @returns
+ */
+function prepareLibrary(library) {
+    // Skip Python libraries and libraries without an initialize.
+    if (library.nativeLibraryModule !== undefined ||
+        library.initialize === undefined) {
+        return library;
+    }
+    return {
+        ...library,
+        initialize: async (context) => {
+            try {
+                await library.initialize(context);
+            }
+            catch (e) {
+                // Ensure we have an `Error` and then `console.error()` it
+                // so that developers see a stack trace of what is going
+                // on.
+                const error = ensureError(e);
+                // Write an empty message which includes a newline to make
+                // it easier to identify the stack trace.
+                console.error("");
+                console.error(error);
+                console.error("");
+                throw error;
+            }
+        },
+    };
+}
 export class Application {
-    constructor({ servicers, initialize, initializeBearerToken, tokenVerifier, }) {
+    constructor({ servicers, libraries, initialize, initializeBearerToken, tokenVerifier, }) {
         _Application_servicers.set(this, void 0);
+        _Application_libraries.set(this, void 0);
         _Application_tokenVerifier.set(this, void 0);
         _Application_express.set(this, void 0);
         _Application_http.set(this, void 0);
         _Application_servers.set(this, void 0);
         _Application_createExternalContext.set(this, void 0);
         _Application_external.set(this, void 0);
-        __classPrivateFieldSet(this, _Application_servicers, servicers, "f");
+        __classPrivateFieldSet(this, _Application_servicers, servicers || [], "f");
+        __classPrivateFieldSet(this, _Application_libraries, libraries || [], "f");
         __classPrivateFieldSet(this, _Application_tokenVerifier, tokenVerifier, "f");
         __classPrivateFieldSet(this, _Application_express, express(), "f");
         // We assume that our users will want these middleware.
@@ -533,7 +583,7 @@ export class Application {
             }
             assert(kind === "initialize");
             return InitializeContext.fromNativeExternal(external);
-        }, servicers, {
+        }, __classPrivateFieldGet(this, _Application_servicers, "f"), {
             start: async (serverId, port, createExternalContext) => {
                 // Store `createExternalContext` function before listening
                 // so we don't attempt to serve any traffic and try and use
@@ -592,11 +642,14 @@ export class Application {
                     throw error;
                 }
             }
-        }, initializeBearerToken, tokenVerifier), "f");
+        }, initializeBearerToken, tokenVerifier, __classPrivateFieldGet(this, _Application_libraries, "f").map(prepareLibrary)), "f");
     }
     get servicers() {
         return __classPrivateFieldGet(this, _Application_servicers, "f");
     }
+    get libraries() {
+        return __classPrivateFieldGet(this, _Application_libraries, "f");
+    }
     get tokenVerifier() {
         return __classPrivateFieldGet(this, _Application_tokenVerifier, "f");
     }
@@ -612,13 +665,25 @@ export class Application {
           please report this issue to the maintainers.`);
             });
         }
+        // Get all the TypeScript libraries and sort them by name.
+        const tsLibraries = __classPrivateFieldGet(this, _Application_libraries, "f")
+            .filter((library) => library.nativeLibraryModule === undefined)
+            .map((library) => library)
+            .sort((a, b) => (a.name > b.name ? 1 : b.name > a.name ? -1 : 0));
+        // Execute pre-run for TypeScript libraries.
+        // Python's NodeApplication responsible for running Python libraries.
+        for (const library of tsLibraries) {
+            if (library.preRun) {
+                library.preRun(this);
+            }
+        }
         return await reboot_native.Application_run(__classPrivateFieldGet(this, _Application_external, "f"));
     }
     get __external() {
         return __classPrivateFieldGet(this, _Application_external, "f");
     }
 }
-_Application_servicers = new WeakMap(), _Application_tokenVerifier = new WeakMap(), _Application_express = new WeakMap(), _Application_http = new WeakMap(), _Application_servers = new WeakMap(), _Application_createExternalContext = new WeakMap(), _Application_external = new WeakMap();
+_Application_servicers = new WeakMap(), _Application_libraries = new WeakMap(), _Application_tokenVerifier = new WeakMap(), _Application_express = new WeakMap(), _Application_http = new WeakMap(), _Application_servers = new WeakMap(), _Application_createExternalContext = new WeakMap(), _Application_external = new WeakMap();
 (function (Application) {
     var _Http_express, _Http_createExternalContext;
     class Http {

package/package.json

@@ -2,11 +2,11 @@
   "dependencies": {
     "@bufbuild/protoplugin": "1.10.1",
     "@bufbuild/protoc-gen-es": "1.10.1",
-    "@reboot-dev/reboot-api": "0.44.0",
+    "@reboot-dev/reboot-api": "0.45.1",
     "chalk": "^4.1.2",
     "node-addon-api": "^7.0.0",
     "node-gyp": ">=10.2.0",
-    "uuid": "^9.0.1",
+    "uuid": "11.1.0",
     "which-pm-runs": "^1.1.0",
     "extensionless": "^1.9.9",
     "esbuild": "^0.24.0",
@@ -22,7 +22,7 @@
   },
   "type": "module",
   "name": "@reboot-dev/reboot",
-  "version": "0.44.0",
+  "version": "0.45.1",
   "description": "npm package for Reboot",
   "scripts": {
     "preinstall": "node preinstall.cjs",
@@ -35,7 +35,6 @@
     "typescript": "5.4.5",
     "@types/express": "^5.0.1",
     "@types/node": "20.11.5",
-    "@types/uuid": "^9.0.4",
     "@types/express-serve-static-core": "^5.0.6"
   },
   "bin": {

package/reboot_native.cc

@@ -86,8 +86,7 @@ struct PythonNodeAdaptor {
             dynamic_cast<const py::error_already_set*>(&e)) {
       // This is a Python exception. Is it an `InputError`?
       if (e_py->matches(
-              py::module::import("rebootdev.aio.exceptions")
-                  .attr("InputError"))) {
+              py::module::import("reboot.aio.exceptions").attr("InputError"))) {
         // This is an InputError, which means it reports a mistake in the input
         // provided by the developer. We want to print _only_ the user-friendly
         // error message in the exception, without intimidating stack traces.
@@ -128,7 +127,7 @@ struct PythonNodeAdaptor {
     if (signal_fd) {
       uint64_t one = 1;
       // Writing to this file descriptor communicates to Python
-      // (see `public/rebootdev/nodejs/python.py`) that
+      // (see `public/reboot/nodejs/python.py`) that
       // `run_functions()` should be called (while holding the Python
       // GIL). In `Initialize()` we've set up `run_functions()` to run
       // the `python_functions` we've just added our callback to.
@@ -398,7 +397,7 @@ void PythonNodeAdaptor::Initialize(
     py::initialize_interpreter();
 
     try {
-      py::object module = py::module::import("rebootdev.nodejs.python");
+      py::object module = py::module::import("reboot.nodejs.python");
 
       module.attr("launch_subprocess_server") =
           py::cpp_function([](py::str py_base64_args) {
@@ -858,7 +857,7 @@ Napi::Promise NodePromiseFromPythonTaskWithContext(
       env,
       std::move(name),
       std::make_tuple(
-          std::string("rebootdev.nodejs.python"),
+          std::string("reboot.nodejs.python"),
           std::string("create_task_with_context"),
           py_context),
       [js_context,  // Ensures `py_context` remains valid.
@@ -963,7 +962,7 @@ py::object PythonFutureFromNodePromise(
                    })});
         } catch (const std::exception& e) {
           // NOTE: we're just catching exception here vs `Napi::Error`
-          // since all we care about is `what()` but we're making sure
+          // since all we care about is `what()` but we're making sue
           // that we'll get all `Napi::Error` with this
           // `static_assert`.
           static_assert(
@@ -1045,7 +1044,7 @@ void ImportPy(const Napi::CallbackInfo& info) {
   std::string base64_encoded_rbt_py = info[1].As<Napi::String>().Utf8Value();
 
   RunCallbackOnPythonEventLoop([&module, &base64_encoded_rbt_py]() {
-    py::module::import("rebootdev.nodejs.python")
+    py::module::import("reboot.nodejs.python")
         .attr("import_py")(module, base64_encoded_rbt_py);
   });
 }
@@ -1081,7 +1080,7 @@ static const napi_type_tag reboot_aio_applications_Application =
 
 
 static const napi_type_tag reboot_aio_external_ExternalContext =
-    MakeTypeTag("rebootdev.aio.external", "ExternalContext");
+    MakeTypeTag("reboot.aio.external", "ExternalContext");
 
 
 Napi::Value python3Path(const Napi::CallbackInfo& info) {
@@ -1268,8 +1267,8 @@ py::object make_py_authorizer(NapiSafeObjectReference js_authorizer) {
       py::is_method(py::none()));
 
   // Now define our subclass.
-  py::object py_parent_class = py::module::import("rebootdev.nodejs.python")
-                                   .attr("NodeAdaptorAuthorizer");
+  py::object py_parent_class =
+      py::module::import("reboot.nodejs.python").attr("NodeAdaptorAuthorizer");
 
   py::object py_parent_metaclass =
       py::reinterpret_borrow<py::object>((PyObject*) &PyType_Type);
@@ -1531,12 +1530,203 @@ py::list make_py_servicers(
 
   // Include memoize servicers by default!
   py_servicers.attr("extend")(
-      py::module::import("rebootdev.aio.memoize").attr("servicers")());
+      py::module::import("reboot.aio.memoize").attr("servicers")());
 
   return py_servicers;
 }
 
 
+struct TypeScriptLibraryDetails {
+  std::string name;
+  std::vector<std::shared_ptr<ServicerDetails>> js_servicers;
+  std::vector<std::string> js_requirements;
+  std::optional<NapiSafeFunctionReference> js_initialize;
+};
+
+struct PythonNativeLibraryDetails {
+  std::string py_library_module;
+  std::string py_library_function;
+  std::optional<NapiSafeObjectReference> js_authorizer;
+};
+
+using LibraryDetails =
+    std::variant<TypeScriptLibraryDetails, PythonNativeLibraryDetails>;
+std::vector<std::shared_ptr<LibraryDetails>> make_library_details(
+    Napi::Env env,
+    const Napi::Array& js_libraries) {
+  std::vector<std::shared_ptr<LibraryDetails>> library_details;
+
+  for (auto&& [_, v] : js_libraries) {
+    Napi::Object js_library = Napi::Value(v).As<Napi::Object>();
+
+    if (!js_library.Get("nativeLibraryModule").IsUndefined()) {
+      std::string module =
+          js_library.Get("nativeLibraryModule").As<Napi::String>().Utf8Value();
+      std::string function = js_library.Get("nativeLibraryFunction")
+                                 .As<Napi::String>()
+                                 .Utf8Value();
+
+      // Get authorizer.
+      std::optional<NapiSafeObjectReference> js_authorizer;
+      if (!js_library.Get("authorizer").IsUndefined()) {
+        js_authorizer = NapiSafeObjectReference(
+            js_library.Get("authorizer").As<Napi::Object>());
+      }
+
+      library_details.push_back(
+          std::make_shared<LibraryDetails>(
+              PythonNativeLibraryDetails{module, function, js_authorizer}));
+    } else if (
+        !js_library.Get("name").IsUndefined()
+        && !js_library.Get("servicers").IsUndefined()) {
+      std::string name = js_library.Get("name").As<Napi::String>().Utf8Value();
+
+      // Get servicers.
+      Napi::Function js_servicers_func =
+          js_library.Get("servicers").As<Napi::Function>();
+      Napi::Value js_servicers_value = js_servicers_func.Call(js_library, {});
+      Napi::Array js_servicers = js_servicers_value.As<Napi::Array>();
+      auto servicer_details = make_servicer_details(env, js_servicers);
+
+      // Get requirements.
+      std::vector<std::string> requirements;
+      if (!js_library.Get("requirements").IsUndefined()) {
+        Napi::Function js_requirements_func =
+            js_library.Get("requirements").As<Napi::Function>();
+        Napi::Value js_requirements_value =
+            js_requirements_func.Call(js_library, {});
+        Napi::Array js_requirements = js_requirements_value.As<Napi::Array>();
+        for (auto&& [_, requirements_v] : js_requirements) {
+          std::string requirement =
+              Napi::Value(requirements_v).As<Napi::String>().Utf8Value();
+          requirements.push_back(requirement);
+        }
+      }
+
+      std::optional<NapiSafeFunctionReference> js_initialize;
+      if (!js_library.Get("initialize").IsUndefined()) {
+        js_initialize = NapiSafeFunctionReference(
+            js_library.Get("initialize").As<Napi::Function>());
+      }
+
+      library_details.push_back(
+          std::make_shared<LibraryDetails>(TypeScriptLibraryDetails{
+              name,
+              servicer_details,
+              requirements,
+              js_initialize}));
+    } else {
+      Napi::Error::New(env, "Unexpected `library` type.")
+          .ThrowAsJavaScriptException();
+    }
+  }
+
+  return library_details;
+}
+
+py::object make_py_typescript_library(
+    TypeScriptLibraryDetails& details,
+    NapiSafeFunctionReference js_from_native_external) {
+  // Construct a subclass of Library.
+  //
+  // What we do below is the recommended way to do that, see:
+  // https://github.com/pybind/pybind11/issues/1193
+
+  // First create all of the attributes that we'll want this
+  // subclass to have.
+  py::dict attributes;
+  attributes["name"] = details.name;
+  attributes["_servicers"] = make_py_servicers(details.js_servicers);
+  attributes["_requirements"] = details.js_requirements;
+  attributes["_initialize"] = py::none();
+
+  if (details.js_initialize.has_value()) {
+    NapiSafeFunctionReference js_initialize = details.js_initialize.value();
+
+    attributes["_initialize"] = py::cpp_function(
+        [js_initialize = std::move(js_initialize),
+         js_from_native_external /* Need a copy because it is shared. ??? */](
+            py::object py_context) mutable {
+          return PythonFutureFromNodePromise(
+              [js_initialize,
+               js_from_native_external,  // NOTE: need a _copy_ of
+                                         // both `js_initialize`
+                                         // and
+                                         // `js_from_native_external`
+                                         // here since
+                                         // `py_initialize` may be
+                                         // called more than once!
+               py_context = new py::object(py_context)](Napi::Env env) mutable {
+                Napi::External<py::object> js_external_context =
+                    make_napi_external(
+                        env,
+                        py_context,
+                        &reboot_aio_external_ExternalContext);
+                Napi::Object js_context =
+                    js_from_native_external.Value(env)
+                        .Call(
+                            env.Global(),
+                            {js_external_context,
+                             Napi::String::New(env, "initialize")})
+                        .As<Napi::Object>();
+
+                return js_initialize.Value(env)
+                    .Call(env.Global(), {js_context})
+                    .As<Napi::Object>();
+              });
+        });
+  }
+
+  // Define the subclass.
+  py::object py_parent_class =
+      py::module::import("reboot.aio.applications").attr("NodeAdaptorLibrary");
+
+  py::object py_parent_metaclass =
+      py::reinterpret_borrow<py::object>((PyObject*) &PyType_Type);
+
+  py::object py_library = py_parent_metaclass(
+      "_NodeAdaptorLibrary",
+      py::make_tuple(py_parent_class),
+      attributes);
+
+  return py_library();
+}
+
+// NOTE: must be called from within _Python_.
+py::list make_py_libraries(
+    const std::vector<std::shared_ptr<LibraryDetails>>& library_details,
+    NapiSafeFunctionReference js_from_native_external) {
+  py::list py_libraries;
+  for (const auto& details : library_details) {
+    if (auto typescript_details =
+            std::get_if<TypeScriptLibraryDetails>(details.get())) {
+      py_libraries.append(make_py_typescript_library(
+          *typescript_details,
+          js_from_native_external));
+    } else if (
+        auto python_details =
+            std::get_if<PythonNativeLibraryDetails>(details.get())) {
+      // Call the library() function with `authorizer` if one is provided.
+      py::object py_library;
+      if (python_details->js_authorizer.has_value()) {
+        py_library =
+            py::module::import(python_details->py_library_module.c_str())
+                .attr(python_details->py_library_function.c_str())(
+                    "authorizer"_a =
+                        make_py_authorizer(*python_details->js_authorizer));
+      } else {
+        py_library =
+            py::module::import(python_details->py_library_module.c_str())
+                .attr(python_details->py_library_function.c_str())();
+      }
+      py_libraries.append(py_library);
+    }
+  }
+
+  return py_libraries;
+}
+
+
 // NOTE: must be called from within _Python_.
 py::object make_py_token_verifier(NapiSafeObjectReference js_token_verifier) {
   // Construct a subclass of TokenVerifier.
@@ -1615,7 +1805,7 @@ py::object make_py_token_verifier(NapiSafeObjectReference js_token_verifier) {
       py::arg("bytes_call"),
       py::is_method(py::none()));
 
-  py::object py_parent_class = py::module::import("rebootdev.nodejs.python")
+  py::object py_parent_class = py::module::import("reboot.nodejs.python")
                                    .attr("NodeAdaptorTokenVerifier");
 
   py::object py_parent_metaclass =
@@ -1672,12 +1862,6 @@ Napi::Value Reboot_up(const Napi::CallbackInfo& info) {
         }
         return py_reboot->attr("up")(
             py_application,
-            // NOTE: while we support subprocess servers
-            // for `rbt dev` and `rbt serve` we do not support
-            // them for tests because we don't have a way to
-            // clone a process like we do with multiprocessing
-            // in Python.
-            "in_process"_a = true,
             "local_envoy"_a = py_local_envoy,
             "local_envoy_port"_a = local_envoy_port);
       },
@@ -1763,8 +1947,8 @@ Napi::Value Reboot_stop(const Napi::CallbackInfo& info) {
   return js_promise;
 }
 
-// NOTE: We block on a promise here, so this method should not be called outside
-// of tests.
+// NOTE: We block on a promise here, so this method should not be called
+// outside of tests.
 Napi::Value Reboot_url(const Napi::CallbackInfo& info) {
   // NOTE: we immediately get a safe reference to the `Napi::External`
   // so that Node will not garbage collect it and the `py::object*` we
@@ -1916,7 +2100,7 @@ Napi::Value Task_await(const Napi::CallbackInfo& info) {
 
   return NodePromiseFromPythonTaskWithContext(
       info.Env(),
-      "rebootdev.nodejs.python.task_await(\"" + state_name + "\", \"" + method
+      "reboot.nodejs.python.task_await(\"" + state_name + "\", \"" + method
           + "\", ...) in nodejs",
       js_external_context,
       [rbt_module = std::move(rbt_module),
@@ -1925,7 +2109,7 @@ Napi::Value Task_await(const Napi::CallbackInfo& info) {
        js_external_context,  // Ensures `py_context` remains valid.
        py_context,
        json_task_id]() {
-        return py::module::import("rebootdev.nodejs.python")
+        return py::module::import("reboot.nodejs.python")
             .attr("task_await")(
                 py_context,
                 py::module::import(rbt_module.c_str()).attr(state_name.c_str()),
@@ -1973,7 +2157,7 @@ Napi::Value ExternalContext_constructor(const Napi::CallbackInfo& info) {
                                     &idempotency_seed,
                                     &idempotency_required,
                                     &idempotency_required_reason]() {
-        py::object py_external = py::module::import("rebootdev.aio.external");
+        py::object py_external = py::module::import("reboot.aio.external");
 
         auto convert_str =
             [](const std::optional<std::string>& optional) -> py::object {
@@ -2007,6 +2191,7 @@ Napi::Value Application_constructor(const Napi::CallbackInfo& info) {
       NapiSafeFunctionReference(info[0].As<Napi::Function>());
 
   Napi::Array js_servicers = info[1].As<Napi::Array>();
+  auto servicer_details = make_servicer_details(info.Env(), js_servicers);
 
   Napi::Object js_web_framework = info[2].As<Napi::Object>();
 
@@ -2016,8 +2201,6 @@ Napi::Value Application_constructor(const Napi::CallbackInfo& info) {
   auto js_web_framework_stop = NapiSafeFunctionReference(
       js_web_framework.Get("stop").As<Napi::Function>());
 
-  auto servicer_details = make_servicer_details(info.Env(), js_servicers);
-
   auto js_initialize = NapiSafeFunctionReference(info[3].As<Napi::Function>());
 
   std::optional<std::string> initialize_bearer_token;
@@ -2030,6 +2213,9 @@ Napi::Value Application_constructor(const Napi::CallbackInfo& info) {
     js_token_verifier = NapiSafeReference(info[5].As<Napi::Object>());
   }
 
+  Napi::Array js_libraries = info[6].As<Napi::Array>();
+  auto library_details = make_library_details(info.Env(), js_libraries);
+
   py::object* py_application = RunCallbackOnPythonEventLoop(
       [servicer_details = std::move(servicer_details),
        js_web_framework_start = std::move(js_web_framework_start),
@@ -2037,8 +2223,11 @@ Napi::Value Application_constructor(const Napi::CallbackInfo& info) {
        initialize_bearer_token = std::move(initialize_bearer_token),
        js_initialize = std::move(js_initialize),
        js_token_verifier,
-       js_from_native_external = std::move(js_from_native_external)]() {
+       js_from_native_external = std::move(js_from_native_external),
+       library_details = std::move(library_details)]() {
         py::list py_servicers = make_py_servicers(servicer_details);
+        py::list py_libraries =
+            make_py_libraries(library_details, js_from_native_external);
 
         py::object py_web_framework_start = py::cpp_function(
             [js_web_framework_start = std::move(js_web_framework_start),
@@ -2105,7 +2294,7 @@ Napi::Value Application_constructor(const Napi::CallbackInfo& info) {
 
                                     return new py::object(
                                         py::module::import(
-                                            "rebootdev.aio.external")
+                                            "reboot.aio.external")
                                             .attr("ExternalContext")(
                                                 "name"_a = py::str(name),
                                                 "channel_manager"_a =
@@ -2216,6 +2405,7 @@ Napi::Value Application_constructor(const Napi::CallbackInfo& info) {
             py::module::import("reboot.aio.applications")
                 .attr("NodeApplication")(
                     "servicers"_a = py_servicers,
+                    "libraries"_a = py_libraries,
                     "web_framework_start"_a = py_web_framework_start,
                     "web_framework_stop"_a = py_web_framework_stop,
                     "initialize"_a = py_initialize,
@@ -2245,7 +2435,7 @@ Napi::Value Application_run(const Napi::CallbackInfo& info) {
   Napi::Promise js_promise = NodePromiseFromPythonTask(
       info.Env(),
       "Application.run() in nodejs",
-      {"rebootdev.nodejs.python", "create_task"},
+      {"reboot.nodejs.python", "create_task"},
       [js_external_application,  // Ensures `py_application` remains valid.
        py_application]() { return py_application->attr("run")(); });
 
@@ -2299,10 +2489,10 @@ Napi::Value Context_generateIdempotentStateId(const Napi::CallbackInfo& info) {
   if (js_alias.IsString()) {
     alias = js_alias.As<Napi::String>().Utf8Value();
   }
-  auto js_each_iteration = idempotency_options.Get("eachIteration");
-  std::optional<bool> each_iteration;
-  if (js_each_iteration.IsBoolean()) {
-    each_iteration = js_each_iteration.As<Napi::Boolean>();
+  auto js_per_iteration = idempotency_options.Get("perIteration");
+  std::optional<bool> per_iteration;
+  if (js_per_iteration.IsBoolean()) {
+    per_iteration = js_per_iteration.As<Napi::Boolean>();
   }
 
   return NodePromiseFromPythonCallback(
@@ -2314,11 +2504,11 @@ Napi::Value Context_generateIdempotentStateId(const Napi::CallbackInfo& info) {
        method = std::move(method),
        key = std::move(key),
        alias = std::move(alias),
-       each_iteration = std::move(each_iteration)]() {
+       per_iteration = std::move(per_iteration)]() {
         // Need to use `call_with_context` to ensure that we have
         // `py_context` as a valid asyncio context variable.
         py::object py_idempotency =
-            py::module::import("rebootdev.nodejs.python")
+            py::module::import("reboot.nodejs.python")
                 .attr("call_with_context")(
                     py::cpp_function([&]() {
                       py::object py_key = py::none();
@@ -2329,16 +2519,17 @@ Napi::Value Context_generateIdempotentStateId(const Napi::CallbackInfo& info) {
                       if (alias.has_value()) {
                         py_alias = py::cast(*alias);
                       }
-                      py::object py_each_iteration = py::none();
-                      if (each_iteration.has_value()) {
-                        py_each_iteration = py::cast(*each_iteration);
+                      py::object py_how = py::none();
+                      if (per_iteration.has_value() && *per_iteration) {
+                        py_how = py::module::import("reboot.aio.idempotency")
+                                     .attr("PER_ITERATION");
                       }
-                      return py::module::import("rebootdev.aio.contexts")
+                      return py::module::import("reboot.aio.contexts")
                           .attr("Context")
                           .attr("idempotency")(
                               "key"_a = py_key,
                               "alias"_a = py_alias,
-                              "each_iteration"_a = py_each_iteration);
+                              "how"_a = py_how);
                     }),
                     py_context);
 
@@ -2394,7 +2585,7 @@ Napi::Value WorkflowContext_loop(const Napi::CallbackInfo& info) {
       [js_external_context,  // Ensures `py_context` remains valid.
        py_context,
        alias = std::move(alias)]() {
-        return py::module::import("rebootdev.nodejs.python")
+        return py::module::import("reboot.nodejs.python")
             .attr("loop")(py_context, alias);
       },
       [](py::object py_iterate) { return new py::object(py_iterate); },
@@ -2472,7 +2663,7 @@ Napi::Value retry_reactively_until(const Napi::CallbackInfo& info) {
                   });
             });
 
-        return py::module::import("rebootdev.aio.contexts")
+        return py::module::import("reboot.aio.contexts")
             .attr("retry_reactively_until")(py_context, py_condition);
       });
 }
@@ -2524,7 +2715,7 @@ Napi::Value memoize(const Napi::CallbackInfo& info) {
                   });
             });
 
-        return py::module::import("rebootdev.aio.memoize")
+        return py::module::import("reboot.aio.memoize")
             .attr("memoize")(
                 py::make_tuple(alias, how),
                 py_context,

package/version.d.ts

@@ -1 +1 @@
-export declare const REBOOT_VERSION = "0.44.0";
+export declare const REBOOT_VERSION = "0.45.1";

package/version.js

@@ -1 +1 @@
-export const REBOOT_VERSION = "0.44.0";
+export const REBOOT_VERSION = "0.45.1";

package/zod-to-proto.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env tsx
-import { toCamelCase, toPascalCase, toSnakeCase, typeSchema, ZOD_ERROR_NAMES, } from "@reboot-dev/reboot-api";
+import { ALLOWED_DEFAULT_BY_CONSTRUCTOR_NAME, toCamelCase, toPascalCase, toSnakeCase, typeSchema, ZOD_ERROR_NAMES, } from "@reboot-dev/reboot-api";
 import { strict as assert } from "assert";
 import chalk from "chalk";
 import { mkdtemp } from "fs/promises";
@@ -56,7 +56,7 @@ const generate = (proto, { schema, path, name, state = false, }) => {
             const { tag } = meta;
             if (tags.has(tag)) {
                 // TODO: give "path" to this property.
-                console.error(chalk.stderr.bold.red(`Trying to use tag ${tag} with property '${key}' already used by '${tags.get(tag)}'`));
+                console.error(chalk.stderr.bold.red(`Trying to use tag '${tag}' with property '${key}' already used by '${tags.get(tag)}'`));
                 process.exit(-1);
             }
             tags.set(tag, key);
@@ -79,7 +79,8 @@ const generate = (proto, { schema, path, name, state = false, }) => {
                                 `primitive type (e.g., string, number, boolean) ` +
                                 `which is immutable or pass a function that creates ` +
                                 `a new ${Array.isArray(firstDefaultValue) ? "array" : "object"} ` +
-                                `each time\n`));
+                                `each time (for example \`reboot_api.EMPTY_ARRAY\` or ` +
+                                `\`reboot_api.EMPTY_RECORD\`).`));
                             process.exit(-1);
                         }
                         // Otherwise, if objects are different, that means that
@@ -401,7 +402,7 @@ const generate = (proto, { schema, path, name, state = false, }) => {
             }
             const { tag } = meta;
             if (tags.has(tag)) {
-                console.error(chalk.stderr.bold.red(`Trying to use already used tag ${tag} in discriminated union`));
+                console.error(chalk.stderr.bold.red(`Trying to use already used tag '${tag}' in discriminated union`));
                 process.exit(-1);
             }
             tags.set(tag, [toSnakeCase(literal), typeName]);
@@ -424,6 +425,121 @@ const generate = (proto, { schema, path, name, state = false, }) => {
         throw new Error(`Unexpected type '${schema._zod.def.type}'`);
     }
 };
+const validateProperDefaultSpecified = (schema, path) => {
+    if (schema instanceof z.ZodObject) {
+        const shape = schema._zod.def.shape;
+        for (const key in shape) {
+            validateProperDefaultSpecified(shape[key], `${path}.${key}`);
+        }
+    }
+    else if (schema instanceof z.ZodRecord) {
+        validateProperDefaultSpecified(schema.valueType, `${path}.[value]`);
+    }
+    else if (schema instanceof z.ZodArray) {
+        validateProperDefaultSpecified(schema.element, `${path}.[item]`);
+    }
+    else if (schema instanceof z.ZodDiscriminatedUnion) {
+        for (const option of schema.options) {
+            // NOTE: The path in the error will be something like:
+            // `api.typeName.methods.methodName.errors.[object Object].field`.
+            validateProperDefaultSpecified(option, `${path}.${option}`);
+        }
+    }
+    else if (schema instanceof z.ZodDefault) {
+        const innerType = schema._zod.def.innerType;
+        const isOptional = innerType instanceof z.ZodOptional;
+        const isObject = innerType instanceof z.ZodObject;
+        const defaultValue = schema._zod.def.defaultValue;
+        // TODO: Write the document about why it is challenging
+        // to have default values in the distributed systems
+        // and attach the link to the error message.
+        if (innerType instanceof z.ZodDiscriminatedUnion) {
+            // Discriminated unions cannot have default values,
+            // because its options will be always different
+            // `z.object` types and we don't support that currently.
+            console.error(chalk.stderr.bold.red(`'${path}' is a discriminated union type and cannot have a ` +
+                `\`default\` value.`));
+            process.exit(-1);
+        }
+        else if (isObject && !isOptional) {
+            console.error(chalk.stderr.bold.red(`'${path}' is a non-optional object type and cannot have a ` +
+                `\`default\` value. Use \`optional()\` for object types with empty default.`));
+            process.exit(-1);
+        }
+        else if (defaultValue === undefined && !isOptional) {
+            console.error(chalk.stderr.bold.red(`'${path}' is a non-optional type and cannot have an ` +
+                `\`undefined\` default value. Change the \`default\` or make the ` +
+                `field \`optional()\`.`));
+            process.exit(-1);
+        }
+        else if (defaultValue !== undefined && isOptional) {
+            console.error(chalk.stderr.bold.red(`'${path}' is an \`optional\` type and can only have ` +
+                `\`undefined\` default value.`));
+            process.exit(-1);
+        }
+        else if (isOptional) {
+            // If the field is `optional` and uses `default=undefined`,
+            // it is valid, check the inner type recursively.
+            validateProperDefaultSpecified(innerType, path);
+            return;
+        }
+        const isEmptyArray = innerType instanceof z.ZodArray &&
+            Array.isArray(defaultValue) &&
+            defaultValue.length === 0;
+        const isEmptyRecord = innerType instanceof z.ZodRecord &&
+            typeof defaultValue === "object" &&
+            defaultValue !== null &&
+            Object.keys(defaultValue).length === 0;
+        const innerTypeConstructorName = innerType.constructor.name;
+        const allowedDefault = 
+        // Return `undefined` if not found.
+        ALLOWED_DEFAULT_BY_CONSTRUCTOR_NAME[innerTypeConstructorName];
+        if (innerType instanceof z.ZodArray) {
+            if (!isEmptyArray) {
+                console.error(chalk.stderr.bold.red(`'${path}' is an \`array\` with an unsupported default value. ` +
+                    `Only empty default value is supported. Use ` +
+                    `\`reboot_api.EMPTY_ARRAY\` to safely specify an empty array default.`));
+                process.exit(-1);
+            }
+        }
+        else if (innerType instanceof z.ZodRecord) {
+            if (!isEmptyRecord) {
+                console.error(chalk.stderr.bold.red(`'${path}' is a \`record\` with an unsupported default value. ` +
+                    `Only empty default value is supported. Use ` +
+                    `\`reboot_api.EMPTY_RECORD\` to safely specify an empty record default.`));
+                process.exit(-1);
+            }
+        }
+        else if (innerType instanceof z.ZodLiteral) {
+            // For Literal types, the default value must be the first literal
+            // value in the list (according to how Protobuf `enum`s work).
+            const firstLiteralValue = innerType._zod.def.values[0];
+            if (defaultValue !== firstLiteralValue) {
+                console.error(chalk.stderr.bold.red(`'${path}' is a \`literal\` with an unsupported default value. ` +
+                    `Only the first literal value \`${firstLiteralValue}\` is ` +
+                    `supported as the default.`));
+                process.exit(-1);
+            }
+        }
+        else if (allowedDefault === undefined) {
+            console.error(chalk.stderr.bold.red(`'${path}' uses \`default\` which is not supported for type ` +
+                `\`${innerTypeConstructorName}\`. Only ` +
+                `${Object.keys(ALLOWED_DEFAULT_BY_CONSTRUCTOR_NAME)
+                    .map((name) => `\`${name}\``)
+                    .join(", ")}` +
+                `, \`ZodArray\`, \`ZodRecord\`, \`ZodLiteral\`, and \`optional\` ` +
+                `types can have a \`default\` currently.`));
+            process.exit(-1);
+        }
+        else if (defaultValue !== allowedDefault) {
+            console.error(chalk.stderr.bold.red(`'${path}' has an unsupported default value. ` +
+                `Supported default value for type \`${innerTypeConstructorName}\` is ` +
+                `\`${JSON.stringify(allowedDefault)}\`.`));
+            process.exit(-1);
+        }
+        validateProperDefaultSpecified(innerType, path);
+    }
+};
 const main = async () => {
     // We generate the `.proto` files in a temporary directory.
     const generatedProtosDirectory = await mkdtemp(path.join(os.tmpdir(), "protos-"));
@@ -501,6 +617,7 @@ const main = async () => {
             // It is safe to do so, because right before that we call
             // 'safeParse()', which ensures that the type is correct.
             const type = result.data;
+            validateProperDefaultSpecified(type.state instanceof z.ZodObject ? type.state : z.object(type.state), `api.${typeName}.state`);
             generate(proto, {
                 schema: type.state instanceof z.ZodObject ? type.state : z.object(type.state),
                 path: `api.${typeName}.state`,
@@ -511,6 +628,7 @@ const main = async () => {
             for (const methodName in type.methods) {
                 // TODO: ensure `methodName` is PascalCase.
                 const { request, response } = type.methods[methodName];
+                validateProperDefaultSpecified(request instanceof z.ZodObject ? request : z.object(request), `api.${typeName}.methods.${methodName}.request`);
                 const requestTypeName = `${typeName}${toPascalCase(methodName)}Request`;
                 generate(proto, {
                     schema: request instanceof z.ZodObject ? request : z.object(request),
@@ -520,6 +638,7 @@ const main = async () => {
                 if (response instanceof z.ZodVoid) {
                     continue;
                 }
+                validateProperDefaultSpecified(response instanceof z.ZodObject ? response : z.object(response), `api.${typeName}.methods.${methodName}.response`);
                 const responseTypeName = `${typeName}${toPascalCase(methodName)}Response`;
                 generate(proto, {
                     schema: response instanceof z.ZodObject ? response : z.object(response),
@@ -554,6 +673,7 @@ const main = async () => {
                     const errors = method.errors instanceof z.ZodDiscriminatedUnion
                         ? method.errors
                         : z.discriminatedUnion("type", method.errors);
+                    validateProperDefaultSpecified(errors, `api.${typeName}.methods.${methodName}.errors`);
                     const path = `api.${typeName}.methods.${methodName}.errors`;
                     const name = `${typeName}${toPascalCase(methodName)}Errors`;
                     errorsToGenerate.push(() => {