durable-actors 0.2.4

package/dist/localRuntime.js

@@ -0,0 +1,112 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { validateProjectId } from "./actor/identity.js";
+import { actorEnvironment } from "./environment.js";
+import { fetchRuntimeExecutablePath } from "./runtimeInstaller.js";
+const connectionSchema = z.object({
+    projectId: z.string().min(1),
+    controlPlaneUrl: z.string().url(),
+    apiKey: z.string().min(1),
+    storageRegion: z.string().min(1),
+    pid: z.number().int().positive()
+});
+/** Resolves when the local server is ready; stopping it preserves its data directory. */
+export async function startLocalActors(options) {
+    validateProjectId(options.projectId);
+    const child = launch(await fetchRuntimeExecutablePath(), options);
+    const { closed, stop } = lifecycle(child);
+    try {
+        const connection = await waitForConnection(child.stdio[3], closed, options.startupTimeoutMs ?? 120_000);
+        return { connection, closed, stop };
+    }
+    catch (error) {
+        await stop().catch(() => { });
+        throw error;
+    }
+}
+function launch(executable, options) {
+    const project = path.resolve(options.project ?? ".");
+    return spawn(executable, [
+        "dev",
+        "--project-id",
+        options.projectId,
+        ...(options.apiKey === undefined ? [] : ["--api-key", options.apiKey]),
+        "--project",
+        project,
+        "--entrypoint",
+        path.resolve(project, options.entrypoint),
+        "--data-dir",
+        path.resolve(project, options.dataDir ?? ".durable-actors"),
+        "--port",
+        String(options.port ?? 0),
+        "--ready-fd",
+        "3",
+        "--sdk-host",
+        fileURLToPath(new URL("./host.js", import.meta.url))
+    ], {
+        cwd: project,
+        env: {
+            ...actorEnvironment(process.env),
+            PATH: `${path.dirname(process.execPath)}${path.delimiter}${path.dirname(executable)}${path.delimiter}${process.env.PATH ?? ""}`,
+            DURABLE_OBJECT_PROCESS_ROLE: "control_plane",
+            DURABLE_OBJECT_PARENT_LIFETIME_STDIN: "1"
+        },
+        stdio: ["pipe", options.quiet ? "ignore" : "inherit", options.quiet ? "ignore" : "inherit", "pipe"]
+    });
+}
+function lifecycle(child) {
+    let stopping = false;
+    const closed = new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("exit", (code, signal) => {
+            if (code === 0 || stopping)
+                resolve();
+            else
+                reject(new Error(`Local actors exited (${signal ?? code})`));
+        });
+    });
+    void closed.catch(() => { });
+    let stopped;
+    const stop = () => (stopped ??= (async () => {
+        stopping = true;
+        child.stdin.end();
+        const timer = setTimeout(() => child.kill("SIGKILL"), 10_000);
+        try {
+            await closed;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    })());
+    return { closed, stop };
+}
+async function waitForConnection(readiness, closed, timeoutMs) {
+    let timer;
+    try {
+        const connection = await Promise.race([
+            readConnection(readiness),
+            closed.then(() => {
+                throw new Error("Local actors exited before readiness");
+            }),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error("Local actors startup timed out")), timeoutMs);
+            })
+        ]);
+        return connection;
+    }
+    finally {
+        clearTimeout(timer);
+        readiness.destroy();
+    }
+}
+async function readConnection(stream) {
+    const chunks = [];
+    for await (const chunk of stream)
+        chunks.push(Buffer.from(chunk));
+    if (chunks.length === 0)
+        throw new Error("Local actors exited without readiness information");
+    return connectionSchema.parse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+}
+//# sourceMappingURL=localRuntime.js.map

package/dist/localRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localRuntime.js","sourceRoot":"","sources":["../src/localRuntime.ts"],"names":[],"mappings":"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"}

package/dist/proxy.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+interface SocketProxyOptions {
+    readonly projectId?: string;
+    readonly controlPlaneUrl?: string;
+    readonly apiKey?: string;
+    readonly setupTimeoutMs?: number;
+}
+interface SocketProxyDependencies {
+    readonly fetch?: typeof globalThis.fetch;
+}
+interface ProxyActor<Metadata = unknown> {
+    readonly types?: Metadata;
+}
+type SocketAuthorization<Actors extends Record<string, ProxyActor>> = {
+    [Name in keyof Actors & string]: {
+        readonly actorName: Name;
+        readonly actorId: string;
+        readonly metadata: Actors[Name] extends ProxyActor<infer Metadata> ? Metadata : never;
+        readonly homeRegion?: string;
+        readonly authorizationLifetimeMs?: number;
+    };
+}[keyof Actors & string];
+declare const socketGrantSchema: z.ZodObject<{
+    websocketUrl: z.ZodURL;
+    transport: z.ZodLiteral<"websocket">;
+    homeRegion: z.ZodString;
+    connectByMs: z.ZodNumber;
+    authorizedUntilMs: z.ZodNumber;
+}, z.core.$strip>;
+type SocketGrant = z.infer<typeof socketGrantSchema>;
+declare class SocketProxy<Actors extends Record<string, ProxyActor>> {
+    private readonly actors;
+    private readonly projectId;
+    private readonly origin;
+    private readonly apiKey;
+    private readonly setupTimeoutMs;
+    private readonly fetchRequest;
+    constructor(actors: Actors, options?: SocketProxyOptions, dependencies?: SocketProxyDependencies);
+    handle(authorization: SocketAuthorization<Actors>): Promise<SocketGrant>;
+}
+export { SocketProxy };
+export type { ProxyActor, SocketAuthorization, SocketGrant, SocketProxyDependencies, SocketProxyOptions };
+//# sourceMappingURL=proxy.d.ts.map

package/dist/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAMvB,UAAU,kBAAkB;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CACnC;AAED,UAAU,uBAAuB;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CAC3C;AAED,UAAU,UAAU,CAAC,QAAQ,GAAG,OAAO;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAA;CAC5B;AAED,KAAK,mBAAmB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,IAAI;KACjE,IAAI,IAAI,MAAM,MAAM,GAAG,MAAM,GAAG;QAC7B,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;QACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;QACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,MAAM,QAAQ,CAAC,GAAG,QAAQ,GAAG,KAAK,CAAA;QACrF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;QAC5B,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAA;KAC5C;CACJ,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAA;AAExB,QAAA,MAAM,iBAAiB;;;;;;iBAMrB,CAAA;AAEF,KAAK,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEpD,cAAM,WAAW,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC;IAQnD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAP3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;gBAGjC,MAAM,EAAE,MAAM,EAC/B,OAAO,GAAE,kBAAuB,EAChC,YAAY,GAAE,uBAA4B;IAwBxC,MAAM,CAAC,aAAa,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC;CA4BjF;AAaD,OAAO,EAAE,WAAW,EAAE,CAAA;AACtB,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,WAAW,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,CAAA"}

package/dist/proxy.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { projectActorPath, validateActorComponent, validateProjectId } from "./actor/identity.js";
+import { socketMetadata } from "./actor/socketValidation.js";
+import { actorEnvironment } from "./environment.js";
+const socketGrantSchema = z.object({
+    websocketUrl: z.url().refine(url => ["ws:", "wss:"].includes(new URL(url).protocol)),
+    transport: z.literal("websocket"),
+    homeRegion: z.string().min(1),
+    connectByMs: z.number().int(),
+    authorizedUntilMs: z.number().int()
+});
+class SocketProxy {
+    actors;
+    projectId;
+    origin;
+    apiKey;
+    setupTimeoutMs;
+    fetchRequest;
+    constructor(actors, options = {}, dependencies = {}) {
+        this.actors = actors;
+        this.setupTimeoutMs = options.setupTimeoutMs ?? 180000;
+        if (!Number.isSafeInteger(this.setupTimeoutMs) || this.setupTimeoutMs < 1000 || this.setupTimeoutMs > 600000)
+            throw new Error("Socket setup timeout must be between one second and ten minutes");
+        const settings = proxySettings(options);
+        const url = new URL(settings.controlPlaneUrl);
+        if (!["https:", "http:"].includes(url.protocol) ||
+            url.pathname !== "/" ||
+            url.search ||
+            url.hash ||
+            url.username ||
+            url.password)
+            throw new Error("Control-plane URL must be an HTTP(S) origin");
+        this.origin = url.origin;
+        this.apiKey = settings.apiKey ?? "";
+        if (typeof this.apiKey !== "string" || !this.apiKey || this.apiKey.trim() !== this.apiKey)
+            throw new Error("A backend shared secret is required; set DURABLE_ACTORS_SECRET or pass apiKey");
+        this.projectId = validateProjectId(settings.projectId);
+        this.fetchRequest = dependencies.fetch ?? globalThis.fetch;
+    }
+    async handle(authorization) {
+        const actorName = validateActorComponent("actor name", authorization.actorName);
+        const actorId = validateActorComponent("actor ID", authorization.actorId);
+        if (!Object.hasOwn(this.actors, actorName))
+            throw new Error(`Unknown actor name: ${actorName}`);
+        const metadata = socketMetadata(authorization.metadata);
+        const authorizationLifetimeMs = authorization.authorizationLifetimeMs ?? 900000;
+        if (!Number.isSafeInteger(authorizationLifetimeMs) ||
+            authorizationLifetimeMs < 1000 ||
+            authorizationLifetimeMs > 86400000)
+            throw new Error("Socket authorization lifetime must be between one second and one day");
+        const homeRegion = authorization.homeRegion === undefined
+            ? undefined
+            : validateActorComponent("home region", authorization.homeRegion);
+        const response = await this.fetchRequest(`${this.origin}${projectActorPath(this.projectId, actorName, actorId)}/connect`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${this.apiKey}`, "content-type": "application/json" },
+            body: JSON.stringify({ transport: "websocket", metadata, authorizationLifetimeMs, homeRegion }),
+            signal: AbortSignal.timeout(this.setupTimeoutMs)
+        });
+        if (!response.ok)
+            throw new Error(`WebSocket authorization could not be issued (HTTP ${response.status})`);
+        return socketGrantSchema.parse(await response.json());
+    }
+}
+function proxySettings(options) {
+    const environment = actorEnvironment(process.env);
+    const controlPlaneUrl = options.controlPlaneUrl ?? environment.DURABLE_ACTORS_CONTROL_PLANE_URL;
+    const apiKey = options.apiKey ?? environment.DURABLE_ACTORS_SECRET;
+    return {
+        projectId: options.projectId ?? environment.DURABLE_ACTORS_PROJECT_ID,
+        controlPlaneUrl: controlPlaneUrl ?? "http://127.0.0.1:7100",
+        apiKey
+    };
+}
+export { SocketProxy };
+//# sourceMappingURL=proxy.js.map

package/dist/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"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"}

package/dist/runtimeInstaller.d.ts

@@ -0,0 +1,16 @@
+export declare function fetchRuntimeExecutablePath(): Promise<string>;
+interface RuntimeOptions {
+    version: string;
+    platform: string;
+    arch: string;
+    cacheDirectory: string;
+}
+export declare class RuntimeInstaller {
+    private readonly options;
+    private readonly download;
+    constructor(options: RuntimeOptions, download?: (url: string) => Promise<Buffer>);
+    install(): Promise<string>;
+    private unpack;
+}
+export {};
+//# sourceMappingURL=runtimeInstaller.d.ts.map

package/dist/runtimeInstaller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeInstaller.d.ts","sourceRoot":"","sources":["../src/runtimeInstaller.ts"],"names":[],"mappings":"AAWA,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,MAAM,CAAC,CAUlE;AAED,UAAU,cAAc;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,EAAE,MAAM,CAAA;CACzB;AAED,qBAAa,gBAAgB;IAErB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,OAAO,EAAE,cAAc,EACvB,QAAQ,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAmB;IAG3E,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;YAuBlB,MAAM;CAsBvB"}

package/dist/runtimeInstaller.js

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+import { chmod, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { x } from "tar";
+import { actorEnvironment } from "./environment.js";
+const executables = ["durable-actors", "durable-actors-modal-go"];
+const maximumBytes = 200 * 1024 * 1024;
+export async function fetchRuntimeExecutablePath() {
+    const environment = actorEnvironment(process.env);
+    if (environment.DURABLE_ACTORS_BINARY)
+        return path.resolve(environment.DURABLE_ACTORS_BINARY);
+    const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+    return new RuntimeInstaller({
+        version,
+        platform: process.platform,
+        arch: process.arch,
+        cacheDirectory: environment.DURABLE_ACTORS_CACHE_DIR ?? path.join(homedir(), ".cache/durable-actors")
+    }).install();
+}
+export class RuntimeInstaller {
+    options;
+    download;
+    constructor(options, download = downloadRelease) {
+        this.options = options;
+        this.download = download;
+    }
+    async install() {
+        const { version, platform, arch, cacheDirectory } = this.options;
+        if (!["darwin", "linux"].includes(platform) || !["arm64", "x64"].includes(arch)) {
+            throw new Error(`No prebuilt runtime for ${platform}/${arch}. On Windows, use WSL 2 with Ubuntu.`);
+        }
+        const destination = path.join(cacheDirectory, version, `${platform}-${arch}`);
+        const binary = path.join(destination, executables[0]);
+        if (await completeBundle(destination))
+            return binary;
+        await mkdir(path.dirname(destination), { recursive: true });
+        const staging = await mkdtemp(`${destination}-`);
+        try {
+            await this.unpack(staging);
+            try {
+                await rename(staging, destination);
+            }
+            catch (error) {
+                if (!(await completeBundle(destination)))
+                    throw error;
+            }
+            return binary;
+        }
+        finally {
+            await rm(staging, { recursive: true, force: true });
+        }
+    }
+    async unpack(directory) {
+        const { version, platform, arch } = this.options;
+        const url = `https://github.com/TerseAI/durable-actors/releases/download/v${version}/durable-actors-${platform}-${arch}.tar.gz`;
+        const [archive, checksum] = await Promise.all([this.download(url), this.download(`${url}.sha256`)]);
+        const expected = checksum.toString("utf8").trim().split(/\s/u)[0];
+        if (!/^[a-f0-9]{64}$/u.test(expected) || createHash("sha256").update(archive).digest("hex") !== expected) {
+            throw new Error("Runtime archive checksum does not match; retry the download.");
+        }
+        const file = path.join(directory, "archive.tar.gz");
+        await writeFile(file, archive);
+        await x({
+            file,
+            cwd: directory,
+            strict: true,
+            filter: (name, entry) => executables.includes(name) && "type" in entry && entry.type === "File" && entry.size <= maximumBytes
+        });
+        await rm(file);
+        if (!(await completeBundle(directory)))
+            throw new Error("Runtime archive is missing its runtime or bundled Modal provider.");
+        await Promise.all(executables.map(name => chmod(path.join(directory, name), 0o755)));
+    }
+}
+async function completeBundle(directory) {
+    return Promise.all(executables.map(name => lstat(path.join(directory, name))
+        .then(stat => stat.isFile() && stat.size > 0)
+        .catch(() => false))).then(results => results.every(Boolean));
+}
+async function downloadRelease(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+    if (!response.ok || !response.body)
+        throw new Error(`Cannot download runtime (HTTP ${response.status}). Check your connection and that this package version has native release assets: ${url}`);
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of response.body) {
+        size += chunk.byteLength;
+        if (size > maximumBytes)
+            throw new Error("Runtime download exceeds the size limit.");
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+}
+//# sourceMappingURL=runtimeInstaller.js.map

package/dist/runtimeInstaller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeInstaller.js","sourceRoot":"","sources":["../src/runtimeInstaller.ts"],"names":[],"mappings":"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"}

package/dist/templates/actor/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Terse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/templates/actor/README.md

@@ -0,0 +1,33 @@
+# Actors
+
+Requires Node.js 22.19.0+, pnpm, and Bun 1.4.2+ on your PATH.
+
+```sh
+pnpm install
+pnpm exec durable-actors dev
+```
+
+Define your actors in `src/durable-objects.ts`. The starter contains a counter with persisted state and `read()` and `increment()` methods. Each counter ID has its own saved value.
+
+`durable-actors dev` watches your actor source and stores local state in `.durable-actors/`. It defaults to project ID `local`; choose another with `pnpm exec durable-actors dev --project-id my-project`. If the CLI is installed globally, you can run `durable-actors dev` directly.
+
+## Connect your application
+
+In your separate application project's directory:
+
+1. Run `pnpm add durable-actors`.
+2. Copy the project ID, URL, and shared secret printed by the actor server into your application’s `.env` file.
+3. Run `durable-actors generate`; the CLI loads `.env` automatically.
+
+Your application backend can then use the generated client:
+
+```ts
+import { actors } from "./generated/index.js"
+
+const counter = actors.Counter.get("example")
+console.log(await counter.increment())
+```
+
+Start your backend with that `.env` file loaded. Update its secret after restarting the actor server. If you change the actor server's URL or port, also set `DURABLE_ACTORS_CONTROL_PLANE_URL` in the backend environment. After changing actor method signatures, rerun the printed generate command in your application.
+
+Use `pnpm check` to check types and `pnpm build` to create `dist/actors.mjs` for deployment.

package/dist/templates/actor/gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+generated/
+.durable-actors/
+.env
+.env.*
+!.env.example

package/dist/templates/actor/package.json

@@ -0,0 +1,20 @@
+{
+    "name": "my-actors",
+    "private": true,
+    "type": "module",
+    "engines": {
+        "node": ">=22.19.0"
+    },
+    "scripts": {
+        "dev": "durable-actors dev",
+        "build": "durable-actors build",
+        "check": "tsc --noEmit"
+    },
+    "dependencies": {
+        "durable-actors": "0.2.4"
+    },
+    "devDependencies": {
+        "@types/node": "^22.0.0",
+        "typescript": "~5.9.3"
+    }
+}

package/dist/templates/actor/src/durable-objects.ts

@@ -0,0 +1,13 @@
+import { Actor, Persisted } from "durable-actors"
+
+export class Counter extends Actor {
+    @Persisted private value = 0
+
+    async read() {
+        return this.value
+    }
+
+    async increment() {
+        return ++this.value
+    }
+}

package/dist/templates/actor/tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "NodeNext",
+        "strict": true,
+        "skipLibCheck": true,
+        "noEmit": true,
+        "types": ["node"]
+    },
+    "include": ["src"]
+}

package/dist/templates/ai-chat/.env.example

@@ -0,0 +1 @@
+OPENAI_API_KEY=

package/dist/templates/ai-chat/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Terse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/templates/ai-chat/README.md

@@ -0,0 +1,41 @@
+# AI chat with durable history
+
+Requires Node.js 20+ and Bun 1.4.2+ on your PATH; Bun executes the actors.
+
+Vercel AI SDK streams replies; a durable actor stores the conversation.
+
+## Run it
+
+```sh
+npx durable-actors init ai-chat-example --template ai-chat
+cd ai-chat-example
+npm install
+```
+
+Copy `.env.example` to `.env` and add your `OPENAI_API_KEY`, then start the actors:
+
+```sh
+npx durable-actors dev
+```
+
+Wait for `Local actors ready`. In another terminal, run the printed export command, then:
+
+```sh
+npm run dev
+```
+
+Open [the chat](http://127.0.0.1:3000), send a message, and reload after the reply finishes. Your history is restored from the actor, including after restarting the servers.
+
+If you already have this directory, start at `npm install`. No client generation is needed for this example.
+
+## The code
+
+- [src/durable-objects.ts](src/durable-objects.ts) stores AI SDK messages in a private `@Persisted` field. Each chat ID gets its own actor.
+- [src/backend.ts](src/backend.ts) loads saved history, appends the new user message, streams a reply, and saves the completed assistant message.
+- [src/Chat.tsx](src/Chat.tsx) loads the lobby history and uses `useChat` to send messages and render streaming replies.
+
+For a remote actor server, use the [connection overrides](../../docs/reference/configuration.md) on the backend.
+
+This sample has one shared lobby and no authentication. Authenticate both routes and check chat ownership before using it for private conversations. Reloads restore saved messages; in-progress streams are not resumed.
+
+See Vercel’s [message persistence guide](https://ai-sdk.dev/docs/ai-sdk-ui/chatbot-message-persistence) for the AI SDK flow.

package/dist/templates/ai-chat/gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+generated/
+.durable-actors/
+.little-actors/
+.env
+.env.*
+!.env.example

package/dist/templates/ai-chat/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>AI chat with durable history</title>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="/src/Chat.tsx"></script>
+    </body>
+</html>

package/dist/templates/ai-chat/package.json

@@ -0,0 +1,30 @@
+{
+    "name": "durable-actors-example-ai-chat",
+    "private": true,
+    "type": "module",
+    "engines": {
+        "node": ">=22.19.0"
+    },
+    "scripts": {
+        "dev": "tsx --env-file=.env src/backend.ts",
+        "build": "tsc --noEmit && vite build"
+    },
+    "dependencies": {
+        "@ai-sdk/openai": "^4.0.65",
+        "@ai-sdk/react": "^4.0.100",
+        "ai": "^7.0.97",
+        "express": "^5.2.1",
+        "durable-actors": "0.2.4",
+        "react": "^19.3.0",
+        "react-dom": "^19.3.0"
+    },
+    "devDependencies": {
+        "@types/express": "^5.0.0",
+        "@types/node": "^22.0.0",
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        "tsx": "^4.0.0",
+        "typescript": "~5.9.3",
+        "vite": "^8.3.0"
+    }
+}

package/dist/templates/ai-chat/src/Chat.tsx

@@ -0,0 +1,37 @@
+import { createRoot } from "react-dom/client"
+
+import { useChat } from "@ai-sdk/react"
+import type { UIMessage } from "ai"
+
+const initialMessages: UIMessage[] = await fetch("/api/chat/lobby").then(response => response.json())
+
+function Chat() {
+    const { messages, sendMessage, status, error } = useChat({ id: "lobby", messages: initialMessages })
+    const busy = status === "submitted" || status === "streaming"
+
+    return (
+        <main>
+            <h1>AI chat</h1>
+            <ul role="log" aria-label="Messages">
+                {messages.map(message => (
+                    <li key={message.id}>
+                        <strong>{message.role}:</strong> {message.parts.map(part => (part.type === "text" ? part.text : "")).join("")}
+                    </li>
+                ))}
+            </ul>
+            <form
+                action={async form => {
+                    await sendMessage({ text: String(form.get("message")) })
+                }}
+            >
+                <label>
+                    Message <input name="message" required disabled={busy} />
+                </label>
+                <button disabled={busy}>{busy ? "Thinking…" : "Send"}</button>
+            </form>
+            {error && <p role="alert">{error.message}</p>}
+        </main>
+    )
+}
+
+createRoot(document.getElementById("root")!).render(<Chat />)