@abstractframework/assistant 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog: AbstractAssistant for the web
+
+All notable changes to the web Assistant (`@abstractframework/assistant` on npm) are documented
+in this file. It is versioned and released independently of the Python package, whose history is
+in the repository [CHANGELOG](../CHANGELOG.md). Release tags for this package are `web-vX.Y.Z`.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-03
+
+First public release on npm. AbstractGateway lists it as **Assistant (web)** and installs it from
+the npm registry (`abstractgateway apps install assistant-web`, or **Install** in the console and
+tray Apps menu); you can also run it yourself with `npx @abstractframework/assistant`.
+It is built on AbstractUIC ui-kit 0.9.14 and panel-chat 0.8.1 (shared bundles re-synced from them) and
+AbstractAvatar 0.1.1.
+
+### Added
+
+- **Conversations in the browser.** Your gateway conversations, grouped by recency and searchable,
+  with live answers, Stop, attachments, copy and export, rendered from the gateway's replay view.
+  Requests that need you are listed first.
+- **Voice.** A Watch-style animated orb: tap to talk (or hold, in Voice settings), dictation into
+  the draft for review or sent automatically, read aloud that follows your voice setting, and
+  playback controls. The composer microphone and the orb share one recording.
+- **Avatar conversation view.** A second view over the same work. Under the avatar, one line shows the
+  latest thing the assistant reports while it works, replaced as soon as something new arrives; click it
+  to read it in full, then **Reply to this** or **Latest** (back to following). The findings it reports
+  (facts or evidence it established) accumulate in a **Findings** panel beside the avatar, a sheet
+  opened with **Findings** on a phone; each opens to the results it came from. The answer appears once,
+  as a message. An open question or approval stays pinned at the top of the view with its buttons on
+  screen, also on a laptop-height window (1000×650); on a very short view its context scrolls inside it
+  while the heading and the buttons stay visible. Needs the producer-typed public updates of AbstractAgent (`kind`) and AbstractRuntime
+  (`update_kind`); older updates are shown as progress. Permission requests use plain actions with the
+  assistant's public explanation when the gateway serves one. The view holds no settings: they open
+  from **Settings** in the conversations sidebar (behind **Open Conversations** on a phone), as
+  everywhere in the app.
+- **Approvals in the conversation.** Deny, Allow once, Allow for this chat or Decide later; a
+  chat's tool policy is stored on the gateway when it offers one.
+- **Avatar designs.** The 44-design AbstractAvatar catalog with previews of every activity state;
+  your choice is kept in this browser. Only avatars with eyes (such as the Hover robot, the Eye, the
+  Rover and the Watch faces and robots) look toward the pointer while Ready, and only their eyes
+  move, easing back to centre after two idle seconds; the orb and every other avatar stay still.
+- **Automations, as on the Apple Watch.** **Automations** beside Conversations lists them in the
+  gateway's order: the active ones first, the most recently active at the top, then **Paused · N** and
+  **Archived · N**, folded until opened (with an older gateway every automation is in one list).
+  Search finds them by name. An automation's page shows how many times it ran, how often and when
+  next, its task and its latest ten runs as a conversation; opening it marks its new results seen.
+  **Run** starts a run now and **Stop** ends the run in progress. **Edit** changes its title, task,
+  whether it is active, how often it runs and whether each run builds on the earlier ones (and how
+  much of them it reads). Talking on its page opens a conversation about its latest run; a run
+  waiting for you opens where you answer it; a tool request is answered on its page (**Deny**,
+  **Approve all**, **Approve**), and **Approve all** lists the tools under **Allowed for its runs**,
+  which this browser then approves when it sees them until **Ask again**. The archive button asks
+  first and **Restore** brings an archived one back. **New** creates one: its task, the flow that
+  runs it, its **Tools** (each Off, Ask or Auto, from the gateway's defaults), every interval from
+  30 seconds to a week or every day at a time, and whether its runs build on each other.
+- **Docs drawer.** Questions about the Assistant answered from its bundled browser guide, separate
+  from your main conversation.
+- **The app server** (`abstractassistant-web`): serves the built app on 127.0.0.1 (port 3008 by
+  default) and under the gateway at `/apps/assistant-web/`, takes the shared app flags
+  (`--gateway-url`, `--port`, `--host`, `--help`), and keeps the gateway session in an HttpOnly
+  cookie so the page never holds a gateway token.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Laurent-Philippe Albou (contact@abstractcore.ai)
+
+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

@@ -1,3 +1,230 @@
-# Temporary Holding Version
+# AbstractAssistant for the web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Assistant's conversation surface in a browser: your conversations, live answers, tool
+approvals and questions in the conversation, attachments, dictation and read aloud. It is a thin
+client of [AbstractGateway](../../abstractgateway/docs/apps.md): the gateway keeps every
+conversation, runs the Assistant's workflow and holds your sign-in. This page keeps no token and
+no copy of your chats; it keeps your display and voice preferences (appearance, panel widths,
+voice overrides, devices, microphone mode) in this browser.
+
+The Watch-inspired layout centres the interaction on a living avatar: tap it to
+talk (or hold, if selected in Voice settings), tap while speaking to pause/resume,
+and use Stop to end playback or the current request. Dictation goes into the draft
+for review unless **Send what you say automatically** is enabled. The pencil moves
+focus to the message field. **Read new replies aloud** uses the same preference as
+Settings → Voice; opening history stays silent. Sending a new message, choosing
+another conversation or starting a new one stops the previous audio.
+
+Settings includes the complete 44-design AbstractAvatar catalog: 34 Watch picker
+designs, three additional Watch shape variants, the iPhone woven orb and six shaded
+avatars. Watch Halo is the default for a new browser; existing selections are preserved.
+The shared generator and AbstractUIC presenter provide previews of Ready,
+Listening, Thinking, Working, Speaking, Waiting and Error, and an animation switch.
+Reduced motion and hidden-page animation are handled by the shared renderer.
+The phone layout keeps the orb above the conversation; wider screens give voice
+and the readable conversation their own space. Conversations are searchable and
+grouped by recency, with requests that need you first.
+
+**Automations**, beside Conversations in the sidebar, does what the Apple Watch assistant does:
+the active automations first and the most recently active at the top, then **Paused · N** and
+**Archived · N** folded until opened (framework ADR 0048; the gateway serves the order and the
+counts, and an older gateway gets every automation in one list), an automation's latest runs as a
+conversation (opening it marks its new results seen), Run and Stop, Edit (title, task, active, how
+often, memory; sent with the revision it was read at), archive and restore, talking about its
+latest run (a new conversation, the automation unchanged), a run's tool request answered on its
+page with **Approve all** filling **Allowed for its runs** (kept in this browser, per account;
+this browser then approves those tools for the automation's runs when it reads the list), and New
+automation with its **Tools** (Off, Ask or Auto per tool; the split rides the definition's
+`policy.tool_policy`). The cards are AbstractUIC's Watch-style `AutomationCard`; the gateway
+calls, the flow picker, the tool editor and the edit and Approve all rules are the kit's
+(`createAutomationsClient`, `AutomationWorkflowPicker`, `ToolModeEditor`, `reviseChanges`,
+`trustAfterApproveAll`). Run-finished notifications stay on the native apps.
+
+The Docs drawer keeps its question field at the bottom and scrolls the conversation
+above it. Its questions use Assistant documentation and stay separate from your
+main conversation. The [browser guide](docs/assistant-guide.md) is bundled as
+`llms.txt` for Gateway to supply to that drawer.
+
+Technical streaming notices belong in **Details**, together with optional usage
+and timing, rather than in the conversation. A structured-output model call may
+deliver its answer all at once; this does not indicate a failed reply. Warnings,
+errors and unanswered approval requests remain visible.
+
+It is composed from the AbstractFramework UI kit (AbstractUIC `ui-kit` + `panel-chat`, ADR 0001
+there): the app shell and its top-right cluster (docs assistant, appearance, about, who is signed
+in, the connection pill), the chat (`WorkflowChat` + `useWorkflowSession`: thread, live replies,
+Stop, attachment chips, copy/export), the one approval panel (`presentInteraction`: Deny / Allow
+once / Allow for this chat / Decide later; the chat's tool policy is stored on the gateway when it
+offers `session_tool_policy`), the run's tool plan, and voice (Settings → Voice, read aloud,
+Tap/Hold to talk). What stays here: the gateway calls (`src/gateway/`), the conversation list and
+its titles, the workflow choice and the run input (desktop parity ports).
+
+Published on npm as [`@abstractframework/assistant`](https://www.npmjs.com/package/@abstractframework/assistant)
+(release history: [CHANGELOG.md](CHANGELOG.md); design: [ADR 0007](../docs/adr/0007_web_assistant.md)).
+Gateway's catalog and tray list it as **Assistant (web)**, next to the desktop Assistant.
+
+## Install
+
+Through AbstractGateway (recommended): open **Apps → Assistant (web) → Install** in the gateway
+console or tray, or run
+
+```bash
+abstractgateway apps install assistant-web --launch
+```
+
+The gateway downloads the package from npm, checks it against the registry's integrity hash,
+installs its one runtime dependency and starts it. Open it from **Apps → Assistant (web)**: the
+one-time handover signs you in at `<gateway>/apps/assistant-web/`.
+
+On its own, with Node.js 18 or newer:
+
+```bash
+npx @abstractframework/assistant --gateway-url http://127.0.0.1:8080
+# or: npm install -g @abstractframework/assistant && abstractassistant-web
+```
+
+It serves on `http://127.0.0.1:3008/`; sign in with a gateway user id and token in the dialog.
+Without `--gateway-url` it follows the local gateway pointer (`~/.abstractframework/gateway.json`),
+then `http://127.0.0.1:8080`.
+
+## Run it against a gateway (development)
+
+Needs Node.js 18 or newer (developed on 24, CI on 22) and a running gateway.
+
+```bash
+cd web
+npm install
+ABSTRACTASSISTANT_GATEWAY_URL=http://127.0.0.1:8080 npm run dev     # http://127.0.0.1:3008/
+```
+
+Sign in with a gateway user id and token in the dialog. The token goes to this app's own server
+(`bin/server.js`), which trades it for a gateway browser session and keeps that in an HttpOnly
+cookie; the page itself never sees a token. Without the variable the server follows the local
+gateway pointer (`~/.abstractframework/gateway.json`), then `http://127.0.0.1:8080`.
+
+## Run the built app
+
+```bash
+npm run build                                   # tsc + vite build + the relative-URL check
+node bin/cli.js --gateway-url http://127.0.0.1:8080 --port 3008
+```
+
+`bin/cli.js` takes the framework's shared app flags (`--gateway-url`, `--port`, `--host`,
+`--help`; abstractuic `app-server`). It listens on 127.0.0.1 only. Gateway detects the
+running app and serves it at `<gateway>/apps/assistant-web/`; open it through Gateway
+Apps to use the signed-in handover.
+
+Dictation needs a secure page: `http://127.0.0.1`/`localhost`, or `https://`. From another
+computer over plain `http://` the microphone button says why it is off.
+
+## Tests
+
+```bash
+npm test                     # vitest: fold, titles, run input and tool-plan parity, workflow choice, the kit transport, hosts, automations
+npm run check:urls           # no root-absolute same-origin URL in the browser code
+npm run build && npm run test:layout   # headless Chromium at 420/760/1024/1280 px, fake gateway
+npm run test:experience      # real UI: virtual mic, draft review, speech ownership, avatar preview, keyboard, reduced motion
+```
+
+`test:layout` needs Playwright's Chromium (`npx playwright install chromium`); add
+`-- --shots <dir>` to `node scripts/check_layout.mjs` to save the screenshots. Below 1024 px it
+emulates a touch device and every target must reach 44 px; from 1024 px (a mouse) the rule covers
+the app's own controls and the kit sizes its own for a fine pointer. It also opens Settings →
+Voice and checks that it names the gateway default and fits, then the automations at
+400/760/1024/1440 px: the list with Paused and Archived opened, an automation's page, Edit and New.
+
+`test:experience` uses a virtual Chromium microphone, silent generated WAV data
+and a fake Gateway. It performs no inference and never opens a physical microphone.
+Both browser checks accept `--shots <dir>` for screenshots.
+
+The session fold runs on the Python tests' own fixture (`tests/basic/fixtures/gateway_runs/`); the
+run-input and tool-list tests run on cases generated BY the desktop's code (CI regenerates both and
+fails on a difference):
+
+```bash
+PYTHONPATH=. python -P web/scripts/gen_run_input_parity.py     # from the repository root
+PYTHONPATH=. python -P web/scripts/gen_tool_policy_parity.py   # needs the package's dependencies
+```
+
+## Layout
+
+| Path | What it is |
+|---|---|
+| `bin/server.js`, `bin/cli.js` | The app server: built files, mount under `/apps/assistant-web/`, gateway session proxy |
+| `src/host/` | What the page needs from its host (gateway URLs, authentication, native capabilities); the browser host |
+| `src/gateway/` | Gateway calls (SSE over fetch, framed by the kit's `sseFrames`) and the kit's `WorkflowTransport` over them, with `replayView` (panel-chat 0.6.2: the conversation, every turn of it, is rendered from the gateway's replay view on AbstractGateway >= 0.17.0, the ledger fold otherwise) |
+| `src/lib/` | Pure logic with tests: session fold, titles, workflow choice, run input, theme group, automations (the list's sections, a new automation's body, runs as messages, its tools and "Allowed for its runs") |
+| `src/ui/` | The Assistant space on the kit: the conversation (`WorkflowChat`), the conversation and automation lists (the shell's navigation), an automation's page, Edit and New, Settings → Voice |
+| `src/vendor/abstractavatar/`, `src/vendor/abstractdocs/` | Generated, hash-checked shared rendering and Docs artifacts; standalone builds use these pinned snapshots |
+| `src/styles/index.css` | App styles on the design tokens of `web/design/tokens.css` |
+| `design/` | Design tokens and mockups (owned separately) |
+
+The npm package (`@abstractframework/assistant`) ships `dist/`, `bin/`, this README, the
+CHANGELOG and the LICENSE; `npm run check:package` lists what a publish would ship and fails on
+anything else. The Python wheel and sdist do not include `web/`.
+
+To adopt a built shared-library update from a workspace checkout, run `npm run sync:avatars`
+and `npm run sync:docs`. Both snapshots come from canonical AbstractUIC implementations. The
+Docs artifact keeps React and the UI kit external so speech and application state retain one
+owner. `npm run build` verifies the committed artifact hashes without needing sibling sources.
+
+### Compact conversation cards
+
+Conversation rows use AbstractUIC's shared Watch-style `SessionCard`: cyan marks unread
+content, orange marks a pending human question or approval, and a small ring marks work.
+Reading clears unread only when loaded content is visible in the focused page. It never
+answers or dismisses a pending approval. Read receipts are local to this browser and account;
+Code and Assistant share them when served on the same origin. Existing history is baselined
+on first use. Regenerate the canonical compatibility snapshot with `npm run sync:sessions`;
+the normal build verifies its provenance. Other devices keep independent read state.
+
+### Message files and tool results
+
+The canonical AbstractUIC conversation snapshot (`npm run sync:conversation`) supplies the
+same message attachments, safe clickable links and structured tool-result viewer in both web
+clients. Files accompany the original user or assistant message, including restored history
+and file-only replies. File bytes load when opened through authenticated reads. The build
+verifies snapshot hashes; no sibling checkout is required to build the committed web app.
+
+Conversation unread marks use the Gateway's account-wide read ledger. Confirmed consumption
+is shared with Code and native clients; failed writes retain the mark. Native clients need
+a build that supports `/api/gateway/me/session-reads`. Attachment previews fit the media
+with one filename, Download, and Close in the shared AbstractUIC dialog.
+
+
+## Avatar conversation view
+
+Choose **Avatar** in the conversation header for a second view over the same work.
+The avatar shows activity and, under it, one live line: the latest thing the assistant
+reports while it works, replaced as soon as something new arrives (nothing cycles). Click
+it to read it in full, then **Reply to this** to answer it or **Latest** to follow again.
+The findings it reports (facts or evidence it established) accumulate in a
+**Findings** panel beside the avatar, or a sheet you open with **Findings** on a phone; open
+one to see the results it came from. The answer appears once, as a message, with Markdown,
+links and files like the conversation.
+**Conversation** restores the ordinary chat and technical details. Switching views
+preserves the current draft and attachments.
+
+Avatar permission requests use ordinary actions, destinations and labeled decision
+icons. “Why I’m asking” shows the assistant’s public explanation when it belongs to
+that exact request. “Review details” opens Conversation mode for technical arguments
+and standing permissions. A missing explanation is stated explicitly.
+
+While work continues, type or speak naturally to guide it. **Reply to this** on the live line pins a
+specific public update as context. Sending a correction makes it available to the
+assistant; the assistant's later response shows whether it adopted the correction.
+Questions use their displayed answer controls. Permission requests require an explicit
+choice; an ordinary message or silence grants no permission.
+
+Essential questions keep waiting. A clarification may state a two-to-five minute
+answer deadline and what will happen without an answer. **Conversation cues** controls
+visual and audio alerts independently for questions, permission requests and completion.
+Audio alerts default off. Voice narration uses the existing voice preference;
+holding the live line, reading the findings sheet or editing a reply silences automatic narration. Playback can be paused
+or silenced without stopping the task.
+
+Public updates require a run started in Avatar mode and a backend supporting the public
+conversation protocol. Switching an already active legacy run changes its presentation;
+it does not manufacture missing updates. Tool details remain available in the ordinary
+view. Public updates describe the assistant's communicated conclusions, not private
+reasoning, and source references establish provenance rather than proof of correctness.

package/bin/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { createGatewayUrlResolver, parseAppFlagsOrExit } from "@abstractframework/app-server";
+
+import { createAssistantServer } from "./server.js";
+
+// The shared launch flags (abstractuic app-server): --gateway-url, --port,
+// --host (default 127.0.0.1: the gateway serves this app at /apps/assistant-web/).
+const flags = parseAppFlagsOrExit(process.argv.slice(2), {
+  appName: "AbstractAssistant Web",
+  command: "abstractassistant-web",
+  envPrefix: "ABSTRACTASSISTANT",
+  defaultPort: 3008,
+});
+
+const fixed = flags.gatewayUrlSource === "flag" || flags.gatewayUrlSource.startsWith("env:");
+const server = createAssistantServer({ defaultGatewayUrl: fixed ? flags.gatewayUrl : createGatewayUrlResolver() });
+
+// A port already in use (or a host this machine does not have) is a one-line
+// error and exit code 1, never a stack trace: the gateway's app manager and a
+// person at a terminal both read the first line.
+server.on("error", (error) => {
+  const where = `${flags.host}:${flags.port}`;
+  const reason =
+    error?.code === "EADDRINUSE"
+      ? `port ${flags.port} is already in use (choose another with --port)`
+      : error?.code === "EADDRNOTAVAIL"
+        ? `${flags.host} is not an address of this computer (see --host)`
+        : String(error?.message || error);
+  console.error(`AbstractAssistant Web could not listen on ${where}: ${reason}`);
+  process.exit(1);
+});
+
+server.listen(flags.port, flags.host, () => {
+  console.log(`AbstractAssistant Web on http://${flags.host}:${flags.port}/ (gateway ${flags.gatewayUrl}, from ${flags.gatewayUrlSource})`);
+});
+
+// Stop promptly: close() alone waits for every open connection, and a live
+// reply stream stays open for minutes, so the open sockets are closed too.
+function shutdown() {
+  server.close(() => process.exit(0));
+  server.closeAllConnections?.();
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/bin/server.js

@@ -0,0 +1,263 @@
+/**
+ * The AbstractAssistant web server: the built app (`dist/`) and the
+ * app-origin gateway session proxy, on the shared app-server kit
+ * (`@abstractframework/app-server`).
+ *
+ * Ported from abstractcode/web/bin/server.js (same contract, fewer routes):
+ * - Serves under the gateway's `/apps/assistant-web/` as well as on its own
+ *   port (`createMountedHandler`: base path from `X-Forwarded-Prefix`, the
+ *   browser's address from a loopback peer's `X-Forwarded-For`, the identity
+ *   header `X-AbstractFramework-App: assistant-web; mount=1`). The shell gets
+ *   `<base href>` (`injectShell`), so every asset and API call resolves under
+ *   the base.
+ * - `/api/connection/gateway` and `/api/gateway/*` go through the kit's
+ *   session proxy (HttpOnly session cookie + CSRF twin at `Path=<base>/`,
+ *   browser `Authorization` and cookies stripped, server-pinned gateway URL).
+ *   The browser never holds a gateway token.
+ * - In front of the proxy, as in abstractcode: a browser mutation must come
+ *   from this app's own origin, a sign-in must be JSON, and a sign-in over a
+ *   loopback socket must name a loopback host (DNS-rebinding guard).
+ *
+ * The gateway catalog registers `assistant-web` separately from the desktop
+ * Assistant (`assistant`), with the cookie prefix `abstractassistant`.
+ */
+import * as http from "node:http";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isIP } from "node:net";
+import { dirname, extname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  createGatewaySessionProxy,
+  createMountedHandler,
+  injectShell,
+  requestContext,
+  socketPeerAddress,
+} from "@abstractframework/app-server";
+
+const BIN_DIR = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_DIST_DIR = resolve(BIN_DIR, "..", "dist");
+/** The gateway's catalog id: `/apps/assistant-web/` and the identity header. */
+export const APP_ID = "assistant-web";
+/** Cookie / CSRF-header prefix: `abstractassistant_gateway_*`, `x-abstractassistant-csrf`. */
+export const COOKIE_APP_ID = "abstractassistant";
+const CONNECTION_PATH = "/api/connection/gateway";
+const GATEWAY_PREFIX = "/api/gateway/";
+const MIME_TYPES = {
+  ".html": "text/html",
+  ".js": "application/javascript",
+  ".css": "text/css",
+  ".json": "application/json",
+  ".txt": "text/plain; charset=utf-8",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".webmanifest": "application/manifest+json",
+  ".woff2": "font/woff2",
+};
+
+function sendJson(res, status, payload) {
+  if (res.headersSent) {
+    res.destroy();
+    return;
+  }
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(payload));
+}
+
+function firstHeader(value) {
+  return String(Array.isArray(value) ? value[0] : value || "")
+    .split(",", 1)[0]
+    .trim();
+}
+
+function mutatingMethod(method) {
+  return ["POST", "PUT", "PATCH", "DELETE"].includes(String(method || "GET").toUpperCase());
+}
+
+function hostnameOf(host) {
+  const raw = String(host || "").trim().toLowerCase();
+  if (raw.startsWith("[")) return raw.slice(1).split("]", 1)[0];
+  return (raw.match(/:/g) || []).length === 1 ? raw.split(":")[0] : raw;
+}
+
+/** `localhost`, `*.localhost`, `::1` or a 127.x IP LITERAL (never a DNS name starting "127."). */
+function isLoopbackHostname(host) {
+  const h = hostnameOf(host);
+  if (h === "localhost" || h.endsWith(".localhost") || h === "::1") return true;
+  return isIP(h) === 4 && h.startsWith("127.");
+}
+
+/** A browser mutation must come from the origin the browser sees this app at. */
+function browserMutationAllowed(req, ctx) {
+  const origin = firstHeader(req.headers.origin);
+  if (origin) {
+    try {
+      return new URL(origin).origin === new URL(`${ctx.proto}://${ctx.host}`).origin;
+    } catch {
+      return false;
+    }
+  }
+  return firstHeader(req.headers["sec-fetch-site"]).toLowerCase() !== "cross-site";
+}
+
+function jsonRequest(req) {
+  return firstHeader(req.headers["content-type"]).split(";", 1)[0].trim().toLowerCase() === "application/json";
+}
+
+function isLoopbackPeerSocket(req) {
+  const peer = socketPeerAddress(req);
+  return peer === "::1" || peer.startsWith("127.");
+}
+
+function trustProxyDeclared() {
+  return ["ABSTRACTASSISTANT_TRUST_PROXY_HEADERS", "ABSTRACTGATEWAY_TRUST_PROXY_HEADERS"].some((name) =>
+    ["1", "true", "yes", "y", "on"].includes(String(process.env[name] || "").trim().toLowerCase()),
+  );
+}
+
+function pathnameOf(req) {
+  return new URL(req.url || "/", "http://abstractassistant.local").pathname;
+}
+
+/**
+ * The gateway half: connection API + `/api/gateway/*`, guarded, then the kit
+ * proxy. Connect-compatible (`next` for every other path), so the Vite dev
+ * server mounts the SAME code.
+ */
+export function createGatewayMiddleware(options = {}) {
+  const proxy = createGatewaySessionProxy({
+    appId: COOKIE_APP_ID,
+    ...(options.defaultGatewayUrl ? { defaultGatewayUrl: options.defaultGatewayUrl } : {}),
+    connectionPath: CONNECTION_PATH,
+    proxyPrefix: GATEWAY_PREFIX,
+  });
+  function middleware(req, res, next) {
+    let pathname;
+    try {
+      pathname = pathnameOf(req);
+    } catch {
+      sendJson(res, 400, { detail: "Invalid request URL" });
+      return;
+    }
+    const owned = pathname === CONNECTION_PATH || pathname.startsWith(GATEWAY_PREFIX);
+    if (!owned) {
+      if (typeof next === "function") next();
+      else sendJson(res, 404, { detail: "Not found" });
+      return;
+    }
+    let ctx;
+    try {
+      ctx = requestContext(req);
+    } catch (error) {
+      sendJson(res, Number(error?.status) || 400, { detail: String(error?.message || error) });
+      return;
+    }
+    if (
+      pathname === CONNECTION_PATH &&
+      mutatingMethod(req.method) &&
+      isLoopbackPeerSocket(req) &&
+      !isLoopbackHostname(req.headers.host) &&
+      !trustProxyDeclared()
+    ) {
+      sendJson(res, 403, {
+        detail: `Sign-in refused: this local app was reached under the host name ${hostnameOf(req.headers.host) || "(none)"}, not a loopback address.`,
+        reason_code: "host_not_allowed",
+      });
+      return;
+    }
+    if (mutatingMethod(req.method) && !browserMutationAllowed(req, ctx)) {
+      sendJson(res, 403, { detail: "Cross-origin browser requests are not allowed", reason_code: "origin_required" });
+      return;
+    }
+    if (pathname === CONNECTION_PATH && req.method === "POST" && !jsonRequest(req)) {
+      sendJson(res, 415, { detail: "Gateway connection requests require Content-Type: application/json" });
+      return;
+    }
+    proxy.handle(req, res, pathname);
+  }
+  middleware.proxy = proxy;
+  return middleware;
+}
+
+function unsafeStaticPath(req) {
+  const rawPath = String(req.url || "/").split("?", 1)[0];
+  let decoded;
+  try {
+    decoded = decodeURIComponent(rawPath);
+  } catch {
+    return true;
+  }
+  return decoded.includes("\0") || decoded.split(/[\\/]+/).includes("..");
+}
+
+function isFile(filePath) {
+  try {
+    return existsSync(filePath) && statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function serveFile(res, filePath) {
+  if (!isFile(filePath)) return false;
+  res.writeHead(200, {
+    "Content-Type": MIME_TYPES[extname(filePath).toLowerCase()] || "application/octet-stream",
+    "Cache-Control": "no-cache",
+  });
+  res.end(readFileSync(filePath));
+  return true;
+}
+
+function serveShell(res, distDir, basePath) {
+  const index = join(distDir, "index.html");
+  if (!isFile(index)) return false;
+  // `host: "browser"` tells the frontend which host adapter to build (src/host/).
+  const html = injectShell(readFileSync(index, "utf8"), { basePath, config: { host: "browser" } });
+  res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-cache" });
+  res.end(html);
+  return true;
+}
+
+export function createAssistantRequestHandler(options = {}) {
+  const distDir = resolve(options.distDir || DEFAULT_DIST_DIR);
+  const gatewayMiddleware = createGatewayMiddleware(options);
+  return createMountedHandler({ appId: APP_ID }, (req, res, ctx) => {
+    gatewayMiddleware(req, res, () => {
+      let pathname;
+      try {
+        pathname = decodeURIComponent(pathnameOf(req));
+      } catch {
+        res.writeHead(400);
+        res.end("Bad Request");
+        return;
+      }
+      if (pathname === "/api" || pathname.startsWith("/api/")) {
+        sendJson(res, 404, { detail: "Not found" });
+        return;
+      }
+      if (unsafeStaticPath(req)) {
+        res.writeHead(400);
+        res.end("Bad Request");
+        return;
+      }
+      if (pathname === "/" || pathname === "/index.html") {
+        if (serveShell(res, distDir, ctx.basePath)) return;
+      }
+      const filePath = resolve(distDir, pathname.replace(/^\/+/, ""));
+      if (filePath !== distDir && !filePath.startsWith(`${distDir}${sep}`)) {
+        res.writeHead(400);
+        res.end("Bad Request");
+        return;
+      }
+      if (serveFile(res, filePath)) return;
+      if (serveShell(res, distDir, ctx.basePath)) return;
+      res.writeHead(404);
+      res.end("Not Found");
+    });
+  });
+}
+
+export function createAssistantServer(options = {}) {
+  return http.createServer(createAssistantRequestHandler(options));
+}