@intentface/latch-server 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intentface
+
+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/README.md

@@ -0,0 +1,92 @@
+# @intentface/latch-server
+
+The mountable HTTP surface for a Latch runtime — **one framework-agnostic Web handler** you mount at a single route in any Web-standard host (TanStack Start, Next, Bun, Deno, serverless).
+
+## What it does
+
+`createLatchHandler({ runtime, connections, resolveContext })` returns a `(Request) => Response` handler that exposes the runtime over HTTP:
+
+- `POST /agents/:agent/:id` — run a chat turn (streams UIMessage SSE).
+- `POST /agents/:agent/:id/approvals` — submit HITL approval decisions (resumes the turn).
+- `POST /agents/:agent/:id/tool-result` — return a client-handled tool result (e.g. `ask_question`).
+- `GET /agents/:agent/:id/history`, `GET /chats`, `GET /runs` — projections for the UI.
+- `GET/POST/DELETE /schedules`, `GET /schedules/:id`, `POST /schedules/:id/run-now` — manage scheduled agents; `POST /cron/run` — the host-guarded tick.
+- `GET /connections`, `…/:name/authorize`, `…/:name/callback`, `…/:name/disconnect`, `…/test` — generic MCP connection OAuth + status.
+
+`resolveContext(request)` turns a request into your `Principal` (bring-your-own auth). A Hono adapter is exported from the `/hono` subpath.
+
+## OAuth callback identity
+
+The connection callback is the one route that does NOT authenticate via
+`resolveContext`. An IdP redirect arrives at a moment you don't control, so a
+degraded session there must never decide where credentials land. Instead,
+`authorize` pins the resolved principal into the OAuth flow state, and the
+callback rebuilds it from that pin:
+
+```ts
+createLatchHandler<Principal>({
+  runtime, connections, resolveContext,
+  // Validate/re-hydrate the pinned identity on the callback (e.g. re-check
+  // org membership). Null → 401. Default: trust the pin as-is.
+  reconstructPrincipal: async (identity) => validateMembership(identity),
+  oauthFlowMaxAgeMs: 30 * 60_000, // authorize → callback TTL (the default)
+});
+```
+
+The callback does **not** resume a waiting turn — the browser must not sit on a
+blank page for a whole run. Resuming is the client's job after the redirect:
+find the pending `connect_<name>` approval in the chat's history, submit it to
+`POST /agents/:agent/:id/approvals`, and read the continuation stream that
+returns. Two details are easy to miss: the continuation reuses the **last
+assistant message's id** and streams only its new parts, so seed your stream
+reader with a clone of that message or the answer renders as a second,
+half-empty one; and mirror the decision locally first, or the approval card
+stays on screen for the whole run. Reconcile against server history at the end.
+
+A callback whose pin is older than `oauthFlowMaxAgeMs` redirects with
+`?error=flow_expired` (the user just re-runs connect). The pin is
+tamper-evident — the full state string is exact-matched against the copy the
+flow stored at `start()` — and principals are IDs-only by contract
+(see `@intentface/latch-core`'s `principal.ts`), so nothing sensitive rides
+in the URL.
+
+## Scheduling over HTTP
+
+`POST /schedules` takes everything `runtime.schedule()` does, so the mounted
+handler is not a reduced version of the contract:
+
+```jsonc
+{
+  "agent": "briefer", "cron": "0 8 * * 1-5", "timezone": "Europe/Helsinki",
+  "prompt": "morning brief",
+  // Opaque to core — only your `runSchedule` hook reads it (a Slack thread, a DM).
+  "delivery": { "kind": "slack", "appId": "A1", "channel": "C1" },
+  // "skip" (default) = don't fire onto a predecessor still waiting on a human;
+  // "fire" = always fire. An unknown value is a 400, never a silent default.
+  "onParked": "fire"
+}
+```
+
+`POST /schedules/:id/run-now` arms a schedule for the next tick rather than
+firing it inline — it then goes through the ordinary `runDue` path (same claim,
+same occurrence consume, same delivery), so "run now" cannot drift from what
+the cron actually does. `GET /runs` deliberately omits each run's `identity`
+(the serialized principal): it is durable server state and a type you are
+invited to extend, so it never enters a browser payload — read it server-side
+via `runtime.listRuns` if you need it.
+
+## Usage
+
+```ts
+import { createLatchHandler } from "@intentface/latch-server";
+
+const handler = createLatchHandler<Principal>({
+  runtime, connections,
+  resolveContext: (req) => getPrincipalFromHeaders(req.headers),
+});
+// mount at /api/latch/* — every Latch operation flows through this one handler.
+```
+
+## Where it fits
+
+The HTTP tier over `@intentface/latch-core`. The routes are a convenience over the real contract — the Runtime operations — which you can still call directly from your own routes or non-HTTP triggers (cron, queues, chat channels).

package/dist/app.d.ts

@@ -0,0 +1,56 @@
+import { type AgentFactory, type ContextDefinition, type Runtime, type RuntimeConfig, type Scheduler, type StorageAdapter } from "@intentface/latch-core";
+import { type ModelCatalog } from "@intentface/latch-core/models";
+import { type LatchHandler, type LatchHandlerConfig } from "./handler.js";
+/**
+ * `createLatchApp` — the composition root you'd otherwise write by hand.
+ *
+ * Given storage, agents and how to resolve the caller, it wires the runtime
+ * with the defaults every host wants (durability on, croner cron evaluator,
+ * the models.dev catalog with pricing / reasoning / web-tool / prompt-caching
+ * hooks, the default harness tools), mounts the HTTP handler over it, and —
+ * on a long-running process — drives `runtime.cron()` on an interval. Every
+ * default is overridable through `runtime` / `handler`; anything a host wants
+ * beyond the defaults (connections, memory, telemetry) goes in the same way.
+ *
+ * A hello-world is the storage adapter plus one agent; see `apps/example`.
+ */
+export interface LatchAppConfig<P, RC = unknown> {
+    /** The storage adapter (e.g. `createSqliteAdapter(db, { owner })`). */
+    storage: StorageAdapter<P>;
+    /**
+     * The agent registry — or a function of the loaded model catalog, so agents
+     * can pick their model from `models.modelFor(...)` without loading the
+     * catalog themselves.
+     */
+    agents: Record<string, AgentFactory<P, RC>> | ((models: ModelCatalog) => Record<string, AgentFactory<P, RC>>);
+    /** Your auth: request → Principal (null → 401). */
+    resolveContext: LatchHandlerConfig<P>["resolveContext"];
+    /** Per-turn runtime context (default: `{}`). */
+    context?: ContextDefinition<P, RC>;
+    /** A preloaded model catalog (default: `loadModelCatalog()`). */
+    models?: ModelCatalog;
+    /** Per-principal cache-key suffix for memory-scoped prompt caching (typically the owner key). */
+    principalKey?: (principal: P) => string;
+    /** Anything else on the runtime — or overrides of the defaults (listed last wins). */
+    runtime?: Partial<Omit<RuntimeConfig<P, RC>, "storage" | "agents" | "context">>;
+    /** Handler options beyond `runtime` / `resolveContext` (basePath, connections, cronSecret, …). */
+    handler?: Partial<Omit<LatchHandlerConfig<P>, "runtime" | "resolveContext">>;
+    /**
+     * In-process cron cadence (ms) driving `runtime.cron()`. Default 30s on a
+     * long-running process; `false` to disable. Auto-disabled on serverless
+     * (VERCEL / AWS_LAMBDA_FUNCTION_NAME set) — point a platform cron at
+     * `POST <basePath>/cron/run` there instead.
+     */
+    cronIntervalMs?: number | false;
+}
+export interface LatchApp<P> {
+    runtime: Runtime<P>;
+    handler: LatchHandler;
+    models: ModelCatalog;
+    /** The in-process cron driver, if one is running. */
+    scheduler?: Scheduler;
+    /** Stop the in-process cron (idempotent). */
+    stop(): Promise<void>;
+}
+export declare function createLatchApp<P, RC = unknown>(cfg: LatchAppConfig<P, RC>): Promise<LatchApp<P>>;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAsC,KAAK,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAEtG,OAAO,EAAsB,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAG9F;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,EAAE,EAAE,GAAG,OAAO;IAC7C,uEAAuE;IACvE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IAC3B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9G,mDAAmD;IACnD,cAAc,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;IACxD,gDAAgD;IAChD,OAAO,CAAC,EAAE,iBAAiB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACnC,iEAAiE;IACjE,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,iGAAiG;IACjG,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,sFAAsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC;IAChF,kGAAkG;IAClG,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,SAAS,GAAG,gBAAgB,CAAC,CAAC,CAAC;IAC7E;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,YAAY,CAAC;IACrB,qDAAqD;IACrD,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,6CAA6C;IAC7C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAQD,wBAAsB,cAAc,CAAC,CAAC,EAAE,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAiDtG"}

package/dist/app.js

@@ -0,0 +1,56 @@
+import { createIntervalScheduler, createRuntime, defineContext, } from "@intentface/latch-core";
+import { loadModelCatalog, providerDefaults } from "@intentface/latch-core/models";
+import { defaultHarnessTools } from "@intentface/latch-core/harness";
+import { createLatchHandler } from "./handler.js";
+import { createCronerEvaluator } from "./cron.js";
+/** Env access without Node types: this package is Web-standard and may run where `process` is absent. */
+const env = (name) => globalThis.process?.env?.[name];
+const SERVERLESS = !!(env("VERCEL") || env("AWS_LAMBDA_FUNCTION_NAME"));
+export async function createLatchApp(cfg) {
+    const models = cfg.models ?? (await loadModelCatalog());
+    const agents = typeof cfg.agents === "function" ? cfg.agents(models) : cfg.agents;
+    const runtime = createRuntime({
+        storage: cfg.storage,
+        context: cfg.context ?? defineContext({ build: () => ({}) }),
+        agents,
+        // Resume-after-crash on by default: it costs a lease heartbeat per turn
+        // and is what makes `cron()`'s sweep half do anything.
+        durability: { enabled: true },
+        cron: createCronerEvaluator(),
+        ...providerDefaults(models, { principalKey: cfg.principalKey }),
+        harnessTools: defaultHarnessTools(),
+        ...cfg.runtime,
+    });
+    const handler = createLatchHandler({
+        runtime,
+        resolveContext: cfg.resolveContext,
+        // The system-wide cron route is unauthenticated — enabled only when a
+        // secret is set (the handler 404s it otherwise).
+        cronSecret: env("LATCH_CRON_SECRET"),
+        ...cfg.handler,
+    });
+    let scheduler;
+    const interval = cfg.cronIntervalMs ?? (SERVERLESS ? false : 30_000);
+    if (interval !== false) {
+        scheduler = createIntervalScheduler({
+            intervalMs: interval,
+            onTick: async () => {
+                const r = await runtime.cron();
+                for (const e of r.errors)
+                    console.error("[latch] cron phase failed:", e);
+            },
+            onError: (e) => console.error("[latch] cron failed:", e),
+        });
+        scheduler.start();
+    }
+    return {
+        runtime,
+        handler,
+        models,
+        scheduler,
+        stop: async () => {
+            await scheduler?.stop();
+        },
+    };
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,aAAa,GAOd,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAqB,MAAM,+BAA+B,CAAC;AACtG,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAA8C,MAAM,cAAc,CAAC;AAC9F,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAuDlD,yGAAyG;AACzG,MAAM,GAAG,GAAG,CAAC,IAAY,EAAsB,EAAE,CAC9C,UAAyE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;AAElG,MAAM,UAAU,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,0BAA0B,CAAC,CAAC,CAAC;AAExE,MAAM,CAAC,KAAK,UAAU,cAAc,CAAkB,GAA0B;IAC9E,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,CAAC,MAAM,gBAAgB,EAAE,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;IAElF,MAAM,OAAO,GAAG,aAAa,CAAQ;QACnC,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,aAAa,CAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAO,EAAE,CAAC;QACzE,MAAM;QACN,wEAAwE;QACxE,uDAAuD;QACvD,UAAU,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE;QAC7B,IAAI,EAAE,qBAAqB,EAAE;QAC7B,GAAG,gBAAgB,CAAQ,MAAM,EAAE,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC;QACtE,YAAY,EAAE,mBAAmB,EAAE;QACnC,GAAG,GAAG,CAAC,OAAO;KACf,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,kBAAkB,CAAI;QACpC,OAAO;QACP,cAAc,EAAE,GAAG,CAAC,cAAc;QAClC,sEAAsE;QACtE,iDAAiD;QACjD,UAAU,EAAE,GAAG,CAAC,mBAAmB,CAAC;QACpC,GAAG,GAAG,CAAC,OAAO;KACf,CAAC,CAAC;IAEH,IAAI,SAAgC,CAAC;IACrC,MAAM,QAAQ,GAAG,GAAG,CAAC,cAAc,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACrE,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;QACvB,SAAS,GAAG,uBAAuB,CAAC;YAClC,UAAU,EAAE,QAAQ;YACpB,MAAM,EAAE,KAAK,IAAI,EAAE;gBACjB,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;gBAC/B,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM;oBAAE,OAAO,CAAC,KAAK,CAAC,4BAA4B,EAAE,CAAC,CAAC,CAAC;YAC3E,CAAC;YACD,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,sBAAsB,EAAE,CAAC,CAAC;SACzD,CAAC,CAAC;QACH,SAAS,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;IAED,OAAO;QACL,OAAO;QACP,OAAO;QACP,MAAM;QACN,SAAS;QACT,IAAI,EAAE,KAAK,IAAI,EAAE;YACf,MAAM,SAAS,EAAE,IAAI,EAAE,CAAC;QAC1B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/cron.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The croner-backed next-fire evaluator for scheduled agents — pass as the
+ * runtime config's `cron`. One implementation so hosts stop copy-pasting the
+ * same three lines (and drift on timezone handling).
+ *
+ * Expressions are interpreted in the schedule's IANA timezone so "9am daily"
+ * means the user's 9am; defaults to UTC when none is set. Returns the next
+ * fire time (epoch ms) strictly after `afterMs`, or null when the expression
+ * never fires again.
+ */
+export declare function createCronerEvaluator(): (expr: string, afterMs: number, timezone?: string) => number | null;
+//# sourceMappingURL=cron.d.ts.map

package/dist/cron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.d.ts","sourceRoot":"","sources":["../src/cron.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,IAAI,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,KACd,MAAM,GAAG,IAAI,CAGjB"}

package/dist/cron.js

@@ -0,0 +1,15 @@
+import { Cron } from "croner";
+/**
+ * The croner-backed next-fire evaluator for scheduled agents — pass as the
+ * runtime config's `cron`. One implementation so hosts stop copy-pasting the
+ * same three lines (and drift on timezone handling).
+ *
+ * Expressions are interpreted in the schedule's IANA timezone so "9am daily"
+ * means the user's 9am; defaults to UTC when none is set. Returns the next
+ * fire time (epoch ms) strictly after `afterMs`, or null when the expression
+ * never fires again.
+ */
+export function createCronerEvaluator() {
+    return (expr, afterMs, timezone) => new Cron(expr, { timezone: timezone || "UTC" }).nextRun(new Date(afterMs))?.getTime() ?? null;
+}
+//# sourceMappingURL=cron.js.map

package/dist/cron.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.js","sourceRoot":"","sources":["../src/cron.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAE9B;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB;IAKnC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,CACjC,IAAI,IAAI,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,QAAQ,IAAI,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,IAAI,CAAC;AAClG,CAAC"}

package/dist/handler.d.ts

@@ -0,0 +1,107 @@
+import type { Runtime } from "@intentface/latch-core";
+import type { McpConnections } from "@intentface/latch-mcp";
+/**
+ * The mountable Latch HTTP surface — one framework-agnostic Web handler.
+ *
+ * `createLatchHandler(config)` returns `(request) => Promise<Response | undefined>`
+ * (`undefined` = "not one of my routes", so the host can 404). Mount it once and
+ * it serves the whole runtime: chat streaming, approvals, chat/run lists,
+ * history, and the *generic* connection OAuth (authorize/callback) + status/
+ * test/disconnect for any MCP connection in the registry. No per-server routes.
+ *
+ * Auth is BYO: `resolveContext(request)` returns the `Principal` (or null →
+ * 401). The core never authenticates; everything is scoped by that principal.
+ *
+ * Routes (relative to `basePath`):
+ *   POST agents/:agent/:id              run a turn (streams a UIMessage Response)
+ *   POST agents/:agent/:id/approvals    submit tool-approval decisions, continue
+ *   GET  chats                          list the tenant's chats
+ *   GET  chats/:id                      client-projected history for one chat
+ *   GET  runs                           list the tenant's runs (usage/cost)
+ *   GET  agents                         the registered agents (for a picker)
+ *   GET  schedules                      list the tenant's scheduled agents
+ *   GET  schedules/:id                  one schedule (404 if not the tenant's)
+ *   POST schedules                      create one ({agent, cron, prompt,
+ *                                       timezone?, delivery?, onParked?})
+ *   POST schedules/:id/run-now          make it due on the next tick
+ *   DELETE schedules/:id                delete one
+ *   POST cron/run                       fire ALL due schedules (host-guarded, no user auth)
+ *   GET  connections                    per-connection status for the tenant
+ *   GET  connections/:name/authorize    begin OAuth → 302 to the IdP
+ *   GET  connections/:name/callback     finish OAuth → 302 back (see below)
+ *   POST connections/:name/disconnect   drop the tenant's stored credentials
+ *   POST connections/:name/test         open the connection, list its tools
+ */
+export interface LatchHandlerConfig<P> {
+    /**
+     * The runtime, or a per-principal resolver. A resolver enables DB-per-tenant
+     * isolation (a separate runtime/DB per tenant, e.g. one SQLite file per
+     * workspace) — it's called after `resolveContext` yields the principal. A
+     * single `Runtime` value fits column-scoped (`owner`) tenancy. Note: `POST
+     * cron/run` (no principal) requires a static runtime OR a `cronRun` tick in
+     * this config (the resolver-based setup's system-wide sweep).
+     */
+    runtime: Runtime<P> | ((principal: P) => Runtime<P> | Promise<Runtime<P>>);
+    /**
+     * Map a request to a Principal (your existing auth). Null → 401.
+     *
+     * NEVER consulted for identity on the OAuth callback: every flow this
+     * handler starts pins the resolved principal into the flow state, and the
+     * callback rebuilds identity from that pin via `reconstructPrincipal`, so a
+     * degraded session at redirect time can never change where credentials land.
+     * A callback whose state carries no pin is rejected as expired.
+     */
+    resolveContext: (request: Request) => P | null | Promise<P | null>;
+    /**
+     * Rebuild a Principal from the identity pinned into the OAuth flow state at
+     * `authorize` time (the mirror of the runtime's `reconstructPrincipal` for
+     * resume/cron). Called on the OAuth callback INSTEAD of `resolveContext` —
+     * the pinned identity is the source of truth; the live session is not
+     * consulted. Override to validate (e.g. re-check org membership) or
+     * re-hydrate; return null to reject the callback (401). Default: cast.
+     */
+    reconstructPrincipal?: (identity: unknown, request: Request) => P | null | Promise<P | null>;
+    /**
+     * Maximum age of an OAuth flow, from `authorize` to `callback`. A callback
+     * whose pinned flow state is older redirects with `?error=flow_expired`.
+     * Default: 30 minutes.
+     */
+    oauthFlowMaxAgeMs?: number;
+    /**
+     * Connection registry (enables the connection routes), or a per-principal
+     * resolver — the latter lets a consumer build a tenant-scoped registry (e.g.
+     * a workspace's installed connectors) after the principal is known.
+     */
+    connections?: McpConnections<P> | ((principal: P) => McpConnections<P> | Promise<McpConnections<P>>);
+    /**
+     * Called after a connection is successfully authorized (both the IdP callback
+     * and the already-authorized short-circuit in `authorize`). A consumer can use
+     * it to flip its own catalog/connector state to active.
+     */
+    onConnected?: (principal: P, connectionName: string) => void | Promise<void>;
+    /**
+     * Query param appended to the post-callback redirect signalling which
+     * connection just connected (`?<connectedParam>=<name>`). Default "connected".
+     */
+    connectedParam?: string;
+    /** Path prefix the handler is mounted under (e.g. "/api/latch"). Default "/". */
+    basePath?: string;
+    /**
+     * Shared secret guarding `POST /cron/run` (the system-wide schedule tick).
+     * When set, the request must send it as `x-latch-cron-secret`. That route is
+     * NOT user-authed — it fires all tenants' due schedules — so guard it at the
+     * host (cron secret / network). Omit to disable the route entirely.
+     */
+    cronSecret?: string;
+    /**
+     * The system-wide tick `POST /cron/run` fires. Required when `runtime` is a
+     * resolver (DB-per-tenant): no principal exists on this route, so the host
+     * must supply the tick that covers its tenants (each `runtime.cron()`). With
+     * a static runtime it defaults to `runtime.cron()` — due schedules fired,
+     * stalled runs reaped and resumed, in one call.
+     */
+    cronRun?: () => Promise<unknown>;
+}
+export type LatchHandler = (request: Request) => Promise<Response | undefined>;
+export declare function createLatchHandler<P>(config: LatchHandlerConfig<P>): LatchHandler;
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgC,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC;;;;;;;OAOG;IACH,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E;;;;;;;;OAQG;IACH,cAAc,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACnE;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,CACrB,QAAQ,EAAE,OAAO,EACjB,OAAO,EAAE,OAAO,KACb,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAClC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,WAAW,CAAC,EACR,cAAc,CAAC,CAAC,CAAC,GACjB,CAAC,CAAC,SAAS,EAAE,CAAC,KAAK,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvE;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,EAAE,cAAc,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,MAAM,YAAY,GAAG,CACzB,OAAO,EAAE,OAAO,KACb,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;AA2GnC,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC5B,YAAY,CAuYd"}