@nyte-ai/host 0.0.0-stage → 0.0.19

package/src/deploy/cloudflare/worker.ts

@@ -0,0 +1,306 @@
+import { asId, SdkError } from "@nyte-ai/schema";
+import type { AdvanceReport, HeadName, Owned, SessionId } from "@nyte-ai/schema";
+import type { Models } from "@nyte-ai/ai";
+import { createModels } from "@nyte-ai/ai/models";
+import { composeHost } from "@nyte-ai/core/server";
+import type { Host, Listener, OpenOptions } from "@nyte-ai/core";
+import type { ServedHost, ServerHost } from "@nyte-ai/core/server";
+import { encodeError, errorStatus } from "@nyte-ai/protocol";
+import { Settings } from "typebox/system";
+import { credentialStore } from "@nyte-ai/host/credentials";
+import { durableObjectStore } from "@nyte-ai/host/durable-object";
+import type { DurableObjectSql, SqlValue } from "@nyte-ai/host/durable-object";
+import { seedSigner } from "@nyte-ai/host/identity";
+import { listenFetch } from "@nyte-ai/host/listen-fetch";
+import { chatOnlyProvider } from "@nyte-ai/host/providers";
+import manifest from "../../../package.json" with { type: "json" };
+
+Settings.Set({ useAcceleration: false });
+
+/** Returns the parts of a Durable Object's `state` `NyteHost` uses, structurally: the storage `durableObjectStore` reads with the object's one alarm, and `blockConcurrencyWhile` to hold requests until the host is composed. */
+export type WorkerState = {
+  readonly storage: DurableObjectSql & {
+    getAlarm(): Promise<number | null>;
+    setAlarm(scheduledTime: number): Promise<void>;
+    deleteAlarm(): Promise<void>;
+  };
+  blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>;
+};
+
+/** Returns the Worker's bindings: the `NyteHost` namespace `wrangler.jsonc` binds, the listener token it requires as a secret (`secrets.required`, set with `wrangler secret put NYTE_TOKEN`, at least 16 characters; §42l), the optional base64 secrets key (decision 10; absent, see `secretsFrom`), and the optional base64 identity seed (§50a; absent, the host answers no identity challenge). */
+export type WorkerEnv = {
+  readonly NYTE_HOST: { getByName(name: string): { fetch(request: Request): Promise<Response> } };
+  readonly NYTE_TOKEN: string;
+  readonly NYTE_SECRET_KEY?: string;
+  readonly NYTE_IDENTITY_KEY?: string;
+};
+
+export type PassBudget = {
+  readonly heads: number;
+  readonly ms: number;
+  readonly repair: boolean;
+};
+
+export type PassHost = Pick<Host, "execution"> & {
+  readonly server: Pick<ServerHost, "tick">;
+};
+
+const PASS_BUDGET = { heads: 32, ms: 10_000 } as const;
+
+const REPAIR_EVERY = 60;
+
+const RETRY_MS = 30_000;
+
+const PAGE = 100;
+
+export function scheduleFrom(report: AdvanceReport, now: number): number | null {
+  switch (report.kind) {
+    case "continue":
+      return now;
+    case "waiting":
+      return report.until;
+    case "retry":
+    case "busy":
+      return report.until;
+    case "idle":
+    case "fenced":
+      return null;
+  }
+}
+
+export async function pass(
+  host: PassHost,
+  storage: Pick<DurableObjectSql, "sql">,
+  budget: PassBudget,
+): Promise<number | null> {
+  const began = Date.now();
+  const schedule = openSchedule(storage);
+  await host.server.tick(began);
+
+  if (budget.repair) {
+    let cursor: Parameters<Host["execution"]["repair"]>[0]["cursor"];
+
+    do {
+      cursor = (await host.execution.repair({ cursor, limit: PAGE })).next ?? undefined;
+    } while (cursor !== undefined);
+  }
+
+  const advances: Promise<void>[] = [];
+
+  for (const entry of schedule.due(Date.now())) {
+    if (advances.length >= budget.heads || Date.now() - began >= budget.ms) {
+      schedule.write(entry.session, entry.head, began);
+
+      continue;
+    }
+
+    advances.push(
+      host.execution.advance({ session: entry.session, head: entry.head }).then(
+        (report) => schedule.settle(entry, scheduleFrom(report, Date.now())),
+        (error: unknown) => {
+          console.error(`Advancing ${entry.session}/${entry.head} failed:`, error);
+          schedule.settle(entry, Date.now() + RETRY_MS);
+        },
+      ),
+    );
+  }
+
+  await Promise.all(advances);
+
+  return schedule.earliest();
+}
+
+/** The Durable Object that is one Nyte host, importing only the node-free subpaths (§41j): composed once per object over its own SQLite storage with a chat-only workspace, served through `listenFetch`, and driven by its alarm. */
+export class NyteHost {
+  readonly #state: WorkerState;
+  readonly #env: WorkerEnv;
+  readonly #models: Models | undefined;
+  #served: Promise<Served> | null = null;
+  #passes = 0;
+
+  constructor(state: WorkerState, env: WorkerEnv, options?: { readonly models?: Models }) {
+    this.#state = state;
+    this.#env = env;
+    this.#models = options?.models;
+    void state.blockConcurrencyWhile(async () => {
+      await this.#serve().catch(() => undefined);
+    });
+  }
+
+  /** Answers one request through the listener once the host is composed; an object whose composition failed answers its encoded `SdkError` (`unavailable`, 503) and composes again on the next request. */
+  async fetch(request: Request): Promise<Response> {
+    let served: Served;
+
+    try {
+      served = await this.#serve();
+    } catch (error) {
+      const failure = new SdkError(
+        "unavailable",
+        `The host did not start: ${error instanceof Error ? error.message : String(error)}`,
+      );
+
+      return new Response(JSON.stringify(encodeError(failure)), {
+        status: errorStatus[failure.code],
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+
+    return served.listener.fetch(request);
+  }
+
+  async alarm(): Promise<void> {
+    const served = await this.#serve();
+    const repair = this.#passes % REPAIR_EVERY === 0;
+    this.#passes += 1;
+    const next = await pass(served.host, this.#state.storage, { ...PASS_BUDGET, repair });
+
+    if (next === null) await this.#state.storage.deleteAlarm();
+    else await this.#state.storage.setAlarm(next);
+  }
+
+  #serve(): Promise<Served> {
+    const served = (this.#served ??= compose(this.#state, this.#env, this.#models));
+
+    served.catch(() => {
+      if (this.#served === served) this.#served = null;
+    });
+
+    return served;
+  }
+}
+
+/** The Worker: routes every request to the one `NyteHost` object, `env.NYTE_HOST.getByName("host")`. */
+export default {
+  async fetch(request: Request, env: WorkerEnv): Promise<Response> {
+    return env.NYTE_HOST.getByName("host").fetch(request);
+  },
+};
+
+type Served = {
+  readonly host: ServedHost;
+  readonly listener: Listener;
+  readonly coverage: Owned;
+};
+
+async function compose(
+  state: WorkerState,
+  env: WorkerEnv,
+  models: Models | undefined,
+): Promise<Served> {
+  const { storage } = state;
+  const store = durableObjectStore(storage);
+  const secrets = secretsFrom(env.NYTE_SECRET_KEY);
+  const description = { name: "nyte-host", platform: "cloudflare", version: manifest.version };
+
+  const host = await composeHost({
+    store,
+    models: models ?? createModels({ credentials: credentialStore(store, secrets) }),
+    plugins: [{ id: "chat-only", environment: chatOnlyProvider() }],
+    workspace: { kind: "chat-only", locator: null },
+    execution: { kind: "admit-only" },
+    secrets,
+    home: null,
+    description,
+  });
+
+  try {
+    const coverage = await host.execution.cover({ kind: "all" });
+    const schedule = openSchedule(storage);
+
+    host.server.onWake((session, head) => {
+      const now = Date.now();
+      schedule.write(session, head, now);
+      void storage.setAlarm(now);
+    });
+
+    const listener = await listenFetch(host, {
+      transport: { kind: "fetch" },
+      auth: { kind: "token", token: env.NYTE_TOKEN },
+      execution: { kind: "admit-only" },
+      describe: () => description,
+      ...(env.NYTE_IDENTITY_KEY === undefined || env.NYTE_IDENTITY_KEY === ""
+        ? {}
+        : {
+            identity: await seedSigner(host.hostId, Uint8Array.fromBase64(env.NYTE_IDENTITY_KEY)),
+          }),
+    });
+
+    await storage.setAlarm(Date.now());
+
+    return { host, listener, coverage };
+  } catch (error) {
+    await host.close();
+
+    throw error;
+  }
+}
+
+function secretsFrom(key: string | undefined): NonNullable<OpenOptions["secrets"]> {
+  if (key === undefined || key === "")
+    return {
+      key: async () => {
+        throw new SdkError("unavailable", "Set NYTE_SECRET_KEY to a base64 32-byte key.");
+      },
+    };
+  const bytes = Uint8Array.from(atob(key), (character) => character.charCodeAt(0));
+
+  return { key: async () => bytes };
+}
+
+function openSchedule(storage: Pick<DurableObjectSql, "sql">) {
+  const rows = (query: string, ...bindings: SqlValue[]): Record<string, SqlValue>[] =>
+    storage.sql.exec(query, ...bindings).toArray();
+
+  rows(
+    "CREATE TABLE IF NOT EXISTS nyte_schedule (session TEXT NOT NULL, head TEXT NOT NULL, at INTEGER NOT NULL, PRIMARY KEY (session, head))",
+  );
+
+  const readAt = (session: SessionId, head: HeadName): number | null => {
+    const at = rows("SELECT at FROM nyte_schedule WHERE session = ? AND head = ?", session, head)[0]
+      ?.at;
+
+    return typeof at === "number" ? at : null;
+  };
+
+  const write = (session: SessionId, head: HeadName, at: number): void => {
+    rows(
+      "INSERT INTO nyte_schedule (session, head, at) VALUES (?, ?, ?) ON CONFLICT (session, head) DO UPDATE SET at = excluded.at",
+      session,
+      head,
+      at,
+    );
+  };
+
+  return {
+    write,
+    due(
+      now: number,
+    ): readonly { readonly session: SessionId; readonly head: HeadName; readonly at: number }[] {
+      return rows(
+        "SELECT session, head, at FROM nyte_schedule WHERE at <= ? ORDER BY at",
+        now,
+      ).flatMap((row) =>
+        typeof row.session === "string" &&
+        typeof row.head === "string" &&
+        typeof row.at === "number"
+          ? [{ session: asId<"session">(row.session), head: asId<"head">(row.head), at: row.at }]
+          : [],
+      );
+    },
+    settle(
+      entry: { readonly session: SessionId; readonly head: HeadName; readonly at: number },
+      next: number | null,
+    ): void {
+      if (readAt(entry.session, entry.head) !== entry.at) return;
+
+      if (next === null)
+        rows("DELETE FROM nyte_schedule WHERE session = ? AND head = ?", entry.session, entry.head);
+      else write(entry.session, entry.head, next);
+    },
+    earliest(): number | null {
+      const at = rows("SELECT MIN(at) AS at FROM nyte_schedule")[0]?.at;
+
+      return typeof at === "number" ? at : null;
+    },
+  };
+}

package/src/deploy/cloudflare/wrangler.jsonc

@@ -0,0 +1,12 @@
+{
+  "name": "nyte-host",
+  "main": "worker.ts",
+  "compatibility_date": "2026-10-02",
+  "compatibility_flags": ["nodejs_compat"],
+  "durable_objects": {
+    "bindings": [{ "name": "NYTE_HOST", "class_name": "NyteHost" }],
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["NyteHost"] }],
+  "secrets": { "required": ["NYTE_TOKEN"] },
+  "observability": { "enabled": true },
+}

package/src/deploy/vercel/README.md

@@ -0,0 +1,3 @@
+# Vercel
+
+This directory is a Nitro app template for running a Nyte host on Vercel; the deployer builds it with `nitro build --preset vercel` (§42m). `nitro.config.ts` serves `server/`, compiles the workflow in `server/workflows` through the `workflow/nitro` integration, lets functions run up to 300 s, and schedules the repair cron. `server/routes/[...].ts` sends every path to the listener of a host composed once per function instance (`server/utils/host.ts`): sessions in Postgres (`DATABASE_URL`), tools in the sandbox named by `NYTE_SANDBOX`, booted by the `boot` you supply in `server/utils/host.ts` over your sandbox SDK (the template carries none; until you do, that workspace answers `unavailable`), and the store re-read every second so each instance sees the others' writes. The host's execution is `dispatch`: after each commit it hands every head a wake makes owed a step to `driveHead` in `server/workflows/drive.ts`, which advances it one step at a time, each step covering its session, sleeps durably between steps until nothing is owed, and ends when another instance holds the head. The cron calls `GET /.nyte/repair` every minute (`NYTE_REPAIR_SCHEDULE` overrides; Hobby plans allow daily only) to dispatch again any head a failed dispatch left owed; that route answers only `Authorization: Bearer <CRON_SECRET>` (compared in constant time; Vercel sends it when `CRON_SECRET` is set), anything else `unauthenticated`, and `unknown` when `CRON_SECRET` is unset (`server/utils/repair.ts`). Jobs run per instance: a client reads another instance's job only through its exit report. Install `nitro` and `workflow` (optional peers of `@nyte-ai/host`; the route reaches h3 through `nitro/h3`) and your sandbox SDK, and set `NYTE_TOKEN` (at least 16 characters), `CRON_SECRET`, to enable `secrets.set`, `NYTE_SECRET_KEY` (base64), and, to answer identity challenges, `NYTE_IDENTITY_KEY` (a base64 32-byte Ed25519 seed; without it `/.nyte/identity` answers `unknown`).

package/src/deploy/vercel/nitro.config.ts

@@ -0,0 +1,29 @@
+import process from "node:process";
+import { defineConfig } from "nitro";
+import type { ModuleOptions } from "workflow/nitro";
+
+const config = {
+  serverDir: "./server",
+  modules: ["workflow/nitro"],
+  workflow: {
+    runtime: "nodejs24.x",
+    dirs: ["./server/workflows"],
+  },
+  vercel: {
+    functions: {
+      runtime: "nodejs24.x",
+      maxDuration: 300,
+    },
+    config: {
+      version: 3,
+      crons: [
+        {
+          path: "/.nyte/repair",
+          schedule: process.env.NYTE_REPAIR_SCHEDULE ?? "* * * * *",
+        },
+      ],
+    },
+  },
+} satisfies Parameters<typeof defineConfig>[0] & { workflow: ModuleOptions };
+
+export default defineConfig(config);

package/src/deploy/vercel/server/routes/[...].ts

@@ -0,0 +1,10 @@
+import { defineHandler } from "nitro/h3";
+import type { H3Event } from "nitro/h3";
+import { vercelHost } from "../utils/host.ts";
+import { dispatchHead } from "../workflows/drive.ts";
+
+async function serve(event: H3Event): Promise<Response> {
+  return (await vercelHost(dispatchHead)).listener.fetch(event.req);
+}
+
+export default defineHandler(serve);

package/src/deploy/vercel/server/utils/host.ts

@@ -0,0 +1,104 @@
+import process from "node:process";
+import { createModels } from "@nyte-ai/ai/models";
+import { SdkError } from "@nyte-ai/schema";
+import { composeHost } from "@nyte-ai/core/server";
+import type { Host, Listener, OpenOptions } from "@nyte-ai/core";
+import type { ServedHost } from "@nyte-ai/core/server";
+import { postgresStore } from "@nyte-ai/host";
+import { credentialStore } from "@nyte-ai/host/credentials";
+import { seedSigner } from "@nyte-ai/host/identity";
+import { listenFetch } from "@nyte-ai/host/listen-fetch";
+import { sandboxProvider } from "@nyte-ai/host/providers";
+import manifest from "../../../../../package.json" with { type: "json" };
+import { answerRepair } from "./repair.ts";
+
+type Served = {
+  readonly host: ServedHost;
+  readonly listener: Listener;
+};
+
+/** Starts the workflow that drives a head; the host hands each wake to it. */
+type Dispatch = Extract<
+  NonNullable<OpenOptions["execution"]>,
+  { readonly kind: "dispatch" }
+>["dispatch"];
+
+const PAGE = 100;
+
+const boot: Parameters<typeof sandboxProvider>[0]["boot"] = async () => {
+  throw new SdkError("unavailable", "Supply a boot over your sandbox SDK in server/utils/host.ts.");
+};
+
+let building: Promise<Served> | null = null;
+
+/** This process's host, composed once, handing each wake to `dispatch`. */
+export function vercelHost(dispatch: Dispatch): Promise<Served> {
+  const built = (building ??= build(dispatch));
+
+  built.catch(() => {
+    if (building === built) building = null;
+  });
+
+  return built;
+}
+
+async function build(dispatch: Dispatch): Promise<Served> {
+  const connectionString = process.env.DATABASE_URL;
+
+  if (connectionString === undefined || connectionString === "")
+    throw new SdkError("unavailable", "Set DATABASE_URL to the Postgres database the host keeps.");
+  const identityKey = process.env.NYTE_IDENTITY_KEY;
+  const store = postgresStore({ connectionString });
+  const secrets = secretsFrom(process.env.NYTE_SECRET_KEY);
+  const description = { name: "nyte-host", platform: "vercel", version: manifest.version };
+
+  const host = await composeHost({
+    store,
+    models: createModels({ credentials: credentialStore(store, secrets) }),
+    plugins: [{ id: "sandbox", environment: sandboxProvider({ boot }) }],
+    workspace: { kind: "sandbox", locator: { name: process.env.NYTE_SANDBOX ?? "nyte" } },
+    execution: { kind: "dispatch", dispatch },
+    poll: 1000,
+    secrets,
+    home: null,
+    description,
+  });
+
+  const repair = async (): Promise<void> => {
+    let cursor: Parameters<Host["execution"]["repair"]>[0]["cursor"];
+
+    do {
+      const page = await host.execution.repair({ cursor, limit: PAGE });
+      cursor = page.next ?? undefined;
+    } while (cursor !== undefined);
+  };
+
+  const listener = await listenFetch(host, {
+    transport: { kind: "fetch" },
+    auth: { kind: "token", token: process.env.NYTE_TOKEN ?? "" },
+    execution: { kind: "admit-only" },
+    describe: () => description,
+    ...(identityKey === undefined || identityKey === ""
+      ? {}
+      : { identity: await seedSigner(host.hostId, Uint8Array.fromBase64(identityKey)) }),
+    before: (request) => answerRepair(request, process.env.CRON_SECRET, repair),
+  }).catch(async (error: unknown) => {
+    await host.close();
+
+    throw error;
+  });
+
+  return { host, listener };
+}
+
+function secretsFrom(key: string | undefined): NonNullable<OpenOptions["secrets"]> {
+  if (key === undefined || key === "")
+    return {
+      key: async () => {
+        throw new SdkError("unavailable", "Set NYTE_SECRET_KEY to a base64 32-byte key.");
+      },
+    };
+  const bytes = new Uint8Array(Buffer.from(key, "base64"));
+
+  return { key: async () => bytes };
+}

package/src/deploy/vercel/server/utils/repair.ts

@@ -0,0 +1,35 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { SdkError } from "@nyte-ai/schema";
+import { encodeError, errorStatus } from "@nyte-ai/protocol";
+
+export async function answerRepair(
+  request: Request,
+  secret: string | undefined,
+  repair: () => Promise<void>,
+): Promise<Response | undefined> {
+  if (request.method !== "GET" || new URL(request.url).pathname !== "/.nyte/repair")
+    return undefined;
+
+  if (secret === undefined || secret === "")
+    return failure(new SdkError("unknown", "This deployment sets no CRON_SECRET."));
+
+  const given = /^Bearer\s+(\S+)\s*$/i.exec(request.headers.get("Authorization") ?? "")?.[1] ?? "";
+
+  if (!timingSafeEqual(digest(given), digest(secret)))
+    return failure(new SdkError("unauthenticated", "Send Authorization: Bearer <CRON_SECRET>."));
+
+  await repair();
+
+  return new Response(null, { status: 204 });
+}
+
+function digest(text: string): Buffer {
+  return createHash("sha256").update(text).digest();
+}
+
+function failure(error: SdkError): Response {
+  return new Response(JSON.stringify(encodeError(error)), {
+    status: errorStatus[error.code],
+    headers: { "Content-Type": "application/json" },
+  });
+}

package/src/deploy/vercel/server/utils/step.ts

@@ -0,0 +1,25 @@
+import type { AdvanceReport } from "@nyte-ai/schema";
+
+export type DriveStep =
+  | { readonly kind: "advance" }
+  | { readonly kind: "sleep"; readonly ms: number }
+  | { readonly kind: "stop" };
+
+export function stepFrom(report: AdvanceReport, now: number): DriveStep {
+  switch (report.kind) {
+    case "continue":
+      return { kind: "advance" };
+    case "waiting":
+      return report.until === null ? { kind: "stop" } : untilStep(report.until, now);
+    case "retry":
+      return untilStep(report.until, now);
+    case "busy":
+    case "idle":
+    case "fenced":
+      return { kind: "stop" };
+  }
+}
+
+function untilStep(until: number, now: number): DriveStep {
+  return until > now ? { kind: "sleep", ms: until - now } : { kind: "advance" };
+}

package/src/deploy/vercel/server/workflows/drive.ts

@@ -0,0 +1,46 @@
+import { sleep } from "workflow";
+import { start } from "workflow/api";
+import type { AdvanceReport, HeadName, SessionId } from "@nyte-ai/schema";
+import { vercelHost } from "../utils/host.ts";
+import { stepFrom } from "../utils/step.ts";
+
+/** Hands a head's wake to the workflow that drives it. */
+export async function dispatchHead(target: {
+  readonly session: SessionId;
+  readonly head: HeadName;
+}): Promise<void> {
+  await start(driveHead, [target]);
+}
+
+export async function driveHead(input: {
+  readonly session: SessionId;
+  readonly head: HeadName;
+}): Promise<void> {
+  "use workflow";
+
+  for (;;) {
+    const next = stepFrom(await advanceHead(input), Date.now());
+
+    if (next.kind === "stop") return;
+
+    if (next.kind === "sleep") await sleep(next.ms);
+  }
+}
+
+export async function advanceHead(input: {
+  readonly session: SessionId;
+  readonly head: HeadName;
+}): Promise<AdvanceReport> {
+  "use step";
+
+  const { host } = await vercelHost(dispatchHead);
+  const coverage = await host.execution.cover({ kind: "sessions", sessions: [input.session] });
+
+  try {
+    await host.server.tick(Date.now());
+
+    return await host.execution.advance(input);
+  } finally {
+    await coverage.close();
+  }
+}

package/src/deploy/vercel/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../../../../tsconfig.base.json",
+  "include": ["**/*.ts"],
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "paths": { "bun": ["./types/bun.d.ts"] }
+  }
+}

package/src/deploy/vercel/types/bun.d.ts

@@ -0,0 +1,2 @@
+/** Stands in for `@types/bun`, which crossws imports from its Bun adapter types, so this program keeps the Node and Web globals the host compiles against (§42r). */
+export {};