@getfamiliar/shared 0.1.13 → 0.1.16

package/build/ChatInput.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Parsing of one line a user typed into a chat (cli-chat, web-chat):
+ * a builtin command of the chat client, a direct handler call
+ * (`/topic/sub …`) or a plain message.
+ */
+/**
+ * Result of {@link parseChatInput}.
+ *
+ * A `handler` arm covers both the plain message (no topic — the chat
+ * plugin's own topic applies) and the `/topic/sub/handler …` direct call,
+ * whose path is the handler's topic.
+ */
+export type ParsedChatInput<Builtin extends string = string> = {
+    readonly kind: "handler";
+    readonly topic?: string;
+    readonly prompt: string;
+    /**
+     * Trimmed raw input line, before slash-command parsing. For direct
+     * calls this is what the chat persists as the `role='user'`
+     * chatmessage (`NewEvent.userChatMessage`), so later chat turns see
+     * exactly what the user typed. For plain messages it equals `prompt`.
+     */
+    readonly rawInput: string;
+} | {
+    readonly kind: "builtin";
+    readonly command: Builtin;
+};
+/**
+ * Parse one raw input line.
+ *
+ * Rules:
+ * - A line whose first word is one of `builtins` → builtin.
+ * - `/a/b … rest` (any other `/` path) → handler call with topic `a:b`;
+ *   anything after the first space is the prompt.
+ * - Anything else (and a bare `/`) → plain message, the trimmed line is
+ *   the prompt.
+ *
+ * @param raw The typed line.
+ * @param builtins The chat client's own commands (e.g. `["/exit", "/clear"]`).
+ * @returns The parsed input.
+ */
+export declare function parseChatInput<Builtin extends string>(raw: string, builtins: readonly Builtin[]): ParsedChatInput<Builtin>;

package/build/ChatInput.js

@@ -0,0 +1,45 @@
+/**
+ * Parsing of one line a user typed into a chat (cli-chat, web-chat):
+ * a builtin command of the chat client, a direct handler call
+ * (`/topic/sub …`) or a plain message.
+ */
+/**
+ * Parse one raw input line.
+ *
+ * Rules:
+ * - A line whose first word is one of `builtins` → builtin.
+ * - `/a/b … rest` (any other `/` path) → handler call with topic `a:b`;
+ *   anything after the first space is the prompt.
+ * - Anything else (and a bare `/`) → plain message, the trimmed line is
+ *   the prompt.
+ *
+ * @param raw The typed line.
+ * @param builtins The chat client's own commands (e.g. `["/exit", "/clear"]`).
+ * @returns The parsed input.
+ */
+export function parseChatInput(raw, builtins) {
+    const line = raw.trim();
+    if (!line.startsWith("/")) {
+        return { kind: "handler", prompt: line, rawInput: line };
+    }
+    const spaceIdx = line.indexOf(" ");
+    const commandPart = spaceIdx === -1 ? line : line.slice(0, spaceIdx);
+    const messagePart = spaceIdx === -1 ? "" : line.slice(spaceIdx + 1).trim();
+    if (builtins.includes(commandPart)) {
+        return { kind: "builtin", command: commandPart };
+    }
+    // Empty segments (trailing `/` or `//`) produce no topic words.
+    const segments = commandPart
+        .slice(1)
+        .split("/")
+        .filter((segment) => segment.length > 0);
+    if (segments.length === 0) {
+        return { kind: "handler", prompt: line, rawInput: line };
+    }
+    return {
+        kind: "handler",
+        topic: segments.join(":"),
+        prompt: messagePart,
+        rawInput: line,
+    };
+}

package/build/ChatMessage.d.ts

@@ -41,6 +41,17 @@ export interface NewChatMessage {
     readonly role: ChatRole;
     readonly textContent: string;
 }
+/** Largest page {@link ChatHistoryQuery.limit} accepts. */
+export declare const MAX_CHAT_HISTORY_PAGE = 200;
+/** Query for one page of a channel's chat history (`ctx.chat.listMessages`). */
+export interface ChatHistoryQuery {
+    /** Channel id (matched against the parent event's `preferred_chat_channel_id`). */
+    readonly channelId: string;
+    /** Only messages with a smaller id (cursor for paging backwards); omit for the newest page. */
+    readonly beforeId?: string;
+    /** Page size, 1 … {@link MAX_CHAT_HISTORY_PAGE}. */
+    readonly limit: number;
+}
 /** Filter for {@link import("./ChatMessageBus").ChatMessageBus.subscribe}. */
 export interface ChatFilter {
     /**

package/build/ChatMessage.js

@@ -8,4 +8,5 @@
  * keeps the container side channel-blind: the agent's `send_chat` tool
  * only needs to know the originating event id, never the channel.
  */
-export {};
+/** Largest page {@link ChatHistoryQuery.limit} accepts. */
+export const MAX_CHAT_HISTORY_PAGE = 200;

package/build/ChatMessageBus.d.ts

@@ -1,4 +1,4 @@
-import type { ChatFilter, ChatMessage, NewChatMessage } from "./ChatMessage.js";
+import type { ChatFilter, ChatHistoryQuery, ChatMessage, NewChatMessage } from "./ChatMessage.js";
 import type { Logger } from "./logging/Logger.js";
 import type { PostgresConnection } from "./PostgresConnection.js";
 /**
@@ -68,6 +68,16 @@ export declare class ChatMessageBus {
      * thread to attach to).
      */
     fetchHistoryForEvent(eventId: string): Promise<ChatMessage[]>;
+    /**
+     * One page of a channel's chat history: the newest `limit` messages
+     * on `channelId` (joined via `events.preferred_chat_channel_id`)
+     * older than `beforeId`, returned oldest first. Page backwards by
+     * passing the first returned id as the next `beforeId`.
+     *
+     * @param query Channel, optional cursor and page size.
+     * @returns Up to `limit` messages in chronological order.
+     */
+    listByChannel(query: ChatHistoryQuery): Promise<ChatMessage[]>;
     /**
      * Subscribe to chat messages matching `filter`. Returns an
      * unsubscribe function.

package/build/ChatMessageBus.js

@@ -85,6 +85,32 @@ export class ChatMessageBus {
              ORDER BY cm.created_at ASC, cm.id ASC`, [eventId]);
         return result.rows.map(mapRow);
     }
+    /**
+     * One page of a channel's chat history: the newest `limit` messages
+     * on `channelId` (joined via `events.preferred_chat_channel_id`)
+     * older than `beforeId`, returned oldest first. Page backwards by
+     * passing the first returned id as the next `beforeId`.
+     *
+     * @param query Channel, optional cursor and page size.
+     * @returns Up to `limit` messages in chronological order.
+     */
+    async listByChannel(query) {
+        const values = [query.channelId, query.limit];
+        const cursor = query.beforeId === undefined ? "" : "AND cm.id < $3";
+        if (query.beforeId !== undefined) {
+            values.push(query.beforeId);
+        }
+        const result = await this.connection.getPool().query(`SELECT * FROM (
+               SELECT cm.*
+               FROM chatmessages cm
+               JOIN events e ON e.id = cm.event_id
+               WHERE e.preferred_chat_channel_id = $1 ${cursor}
+               ORDER BY cm.id DESC
+               LIMIT $2
+             ) page
+             ORDER BY page.id ASC`, values);
+        return result.rows.map(mapRow);
+    }
     /**
      * Subscribe to chat messages matching `filter`. Returns an
      * unsubscribe function.

package/build/DockerTools.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Shared bridge network all Familiar containers join. Owned
+ * by the daemon (see `commands/Start.ts`); created once via
+ * {@link ensureNetwork} before any container is started.
+ */
+export declare const SHARED_NETWORK_NAME = "familiar-net";
+/**
+ * Internal (egress-less) bridge network the locked-down agent container
+ * joins. Created with `--internal` so the agent has no route to the
+ * internet; it reaches postgres (dual-homed onto this net) and the host
+ * bastion (via the `familiar-bastion-bridge` socat sidecar, also on this
+ * net) by container name. Owned by the daemon, created via
+ * {@link ensureNetwork} with `{ internal: true }`.
+ */
+export declare const ISOLATED_NETWORK_NAME = "familiar-isolated";
+/** Options shared by {@link dockerExec}. */
+export interface DockerExecOptions {
+    /** If true, non-zero exit codes resolve instead of throwing. */
+    readonly allowFailure?: boolean;
+}
+/** Output of {@link dockerCapture}. */
+export interface DockerCaptureResult {
+    readonly code: number | null;
+    readonly stdout: string;
+}
+/**
+ * Run a docker CLI command and discard its stdio. Resolves on exit
+ * code 0 (or always when `allowFailure` is set); rejects otherwise.
+ */
+export declare function dockerExec(args: readonly string[], options?: DockerExecOptions): Promise<void>;
+/**
+ * Run a docker CLI command and capture stdout. Never throws on non-zero
+ * exit; callers inspect the returned `code`.
+ */
+export declare function dockerCapture(args: readonly string[]): Promise<DockerCaptureResult>;
+/** Whether a container with the given name is currently running. */
+export declare function isContainerRunning(name: string): Promise<boolean>;
+/** Whether a Docker network with the given name already exists. */
+export declare function isNetworkPresent(name: string): Promise<boolean>;
+/**
+ * Whether a Docker image with the given reference is present in the
+ * local image store. Used by the pull-mode image lifecycle to avoid
+ * re-pulling a version-pinned image that's already local.
+ *
+ * @param ref Image reference (tag or registry-qualified `name:tag`).
+ * @returns true if `docker image inspect` succeeds.
+ */
+export declare function isImagePresent(ref: string): Promise<boolean>;
+/** Options for {@link buildNetworkCreateArgs} / {@link ensureNetwork}. */
+export interface NetworkCreateOptions {
+    /**
+     * Create the network with `--internal` so containers on it have no
+     * egress to the host or the internet — only to other containers on
+     * the same network. Used for the agent's `familiar-isolated` net.
+     */
+    readonly internal?: boolean;
+}
+/**
+ * Build the `docker network create` argument vector. Pure (no side
+ * effects) so it can be unit-tested without a daemon.
+ *
+ * @param name Network name to create.
+ * @param options Network creation flags (e.g. `internal`).
+ * @returns The full docker CLI argv, e.g. `["network", "create", "--internal", "familiar-isolated"]`.
+ */
+export declare function buildNetworkCreateArgs(name: string, options?: NetworkCreateOptions): string[];
+/**
+ * Create the named bridge network if it doesn't already exist. Idempotent.
+ *
+ * @param name Network name to ensure.
+ * @param options Network creation flags applied only on first creation
+ *   (an existing network is left as-is).
+ */
+export declare function ensureNetwork(name: string, options?: NetworkCreateOptions): Promise<void>;
+/**
+ * Attach an already-running container to an additional network by name.
+ * Callers recreate their container on every `start()` (via
+ * {@link removeContainer} first), so the attachment is always fresh —
+ * this throws on failure rather than swallowing it, so a genuine
+ * problem (missing network, missing container) surfaces instead of
+ * silently leaving the container unable to reach its peer.
+ *
+ * @param network Network to connect the container to.
+ * @param container Name of the running container to attach.
+ * @throws If the docker command fails (network/container missing, etc.).
+ */
+export declare function connectNetwork(network: string, container: string): Promise<void>;
+/**
+ * Force-remove a container by name. Default `allowFailure: true` because
+ * "remove if it exists" is the common idempotent-cleanup intent.
+ */
+export declare function removeContainer(name: string, options?: DockerExecOptions): Promise<void>;
+/** Send `docker stop` to a container. Ignores already-stopped/missing containers. */
+export declare function stopContainer(name: string): Promise<void>;
+/**
+ * Run a docker CLI command with the parent process's stdin/stdout/
+ * stderr inherited, blocking until the child exits. Used by
+ * subcommands that hand the user's terminal to a foreground docker
+ * process (`familiar psql`'s psql shell, `familiar mcp call`'s
+ * one-shot CLI invocations against an MCP runtime container).
+ *
+ * Returns the child's exit status — `null`-on-signal collapses to
+ * 1 so the caller's `process.exit(...)` always sees a usable
+ * number. A failure to launch docker itself (e.g. binary missing)
+ * surfaces as a thrown {@link Error} the caller can format.
+ *
+ * @throws If the docker binary couldn't be spawned at all.
+ */
+export declare function dockerInteractive(args: readonly string[]): number;
+/**
+ * On Linux, `host.docker.internal` isn't built-in and must be mapped to
+ * the host gateway explicitly. macOS and Windows resolve it natively.
+ *
+ * Used by sidecars that dial a host-side listener (the bastion bridge,
+ * the tailscale plugin's serve proxy to the webserver).
+ *
+ * @returns Extra `docker run` args, or an empty array on macOS/Windows.
+ */
+export declare function hostGatewayArgs(): string[];

package/build/DockerTools.js

@@ -0,0 +1,175 @@
+import { spawn, spawnSync } from "node:child_process";
+import os from "node:os";
+/**
+ * Shared bridge network all Familiar containers join. Owned
+ * by the daemon (see `commands/Start.ts`); created once via
+ * {@link ensureNetwork} before any container is started.
+ */
+export const SHARED_NETWORK_NAME = "familiar-net";
+/**
+ * Internal (egress-less) bridge network the locked-down agent container
+ * joins. Created with `--internal` so the agent has no route to the
+ * internet; it reaches postgres (dual-homed onto this net) and the host
+ * bastion (via the `familiar-bastion-bridge` socat sidecar, also on this
+ * net) by container name. Owned by the daemon, created via
+ * {@link ensureNetwork} with `{ internal: true }`.
+ */
+export const ISOLATED_NETWORK_NAME = "familiar-isolated";
+/**
+ * Run a docker CLI command and discard its stdio. Resolves on exit
+ * code 0 (or always when `allowFailure` is set); rejects otherwise.
+ */
+export function dockerExec(args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn("docker", [...args], { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        proc.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        proc.on("close", (code) => {
+            if (code === 0 || options.allowFailure) {
+                resolve();
+                return;
+            }
+            const trimmed = stderr.trim();
+            const suffix = trimmed.length > 0 ? `: ${trimmed}` : "";
+            reject(new Error(`docker ${args.join(" ")} exited with code ${code}${suffix}`));
+        });
+        proc.on("error", reject);
+    });
+}
+/**
+ * Run a docker CLI command and capture stdout. Never throws on non-zero
+ * exit; callers inspect the returned `code`.
+ */
+export function dockerCapture(args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn("docker", [...args], { stdio: ["ignore", "pipe", "ignore"] });
+        let stdout = "";
+        proc.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        proc.on("close", (code) => {
+            resolve({ code, stdout });
+        });
+        proc.on("error", reject);
+    });
+}
+/** Whether a container with the given name is currently running. */
+export async function isContainerRunning(name) {
+    const { code, stdout } = await dockerCapture([
+        "container",
+        "inspect",
+        "-f",
+        "{{.State.Running}}",
+        name,
+    ]);
+    return code === 0 && stdout.trim() === "true";
+}
+/** Whether a Docker network with the given name already exists. */
+export async function isNetworkPresent(name) {
+    const { code } = await dockerCapture(["network", "inspect", name]);
+    return code === 0;
+}
+/**
+ * Whether a Docker image with the given reference is present in the
+ * local image store. Used by the pull-mode image lifecycle to avoid
+ * re-pulling a version-pinned image that's already local.
+ *
+ * @param ref Image reference (tag or registry-qualified `name:tag`).
+ * @returns true if `docker image inspect` succeeds.
+ */
+export async function isImagePresent(ref) {
+    const { code } = await dockerCapture(["image", "inspect", ref]);
+    return code === 0;
+}
+/**
+ * Build the `docker network create` argument vector. Pure (no side
+ * effects) so it can be unit-tested without a daemon.
+ *
+ * @param name Network name to create.
+ * @param options Network creation flags (e.g. `internal`).
+ * @returns The full docker CLI argv, e.g. `["network", "create", "--internal", "familiar-isolated"]`.
+ */
+export function buildNetworkCreateArgs(name, options = {}) {
+    const args = ["network", "create"];
+    if (options.internal) {
+        args.push("--internal");
+    }
+    args.push(name);
+    return args;
+}
+/**
+ * Create the named bridge network if it doesn't already exist. Idempotent.
+ *
+ * @param name Network name to ensure.
+ * @param options Network creation flags applied only on first creation
+ *   (an existing network is left as-is).
+ */
+export async function ensureNetwork(name, options = {}) {
+    if (!(await isNetworkPresent(name))) {
+        await dockerExec(buildNetworkCreateArgs(name, options));
+    }
+}
+/**
+ * Attach an already-running container to an additional network by name.
+ * Callers recreate their container on every `start()` (via
+ * {@link removeContainer} first), so the attachment is always fresh —
+ * this throws on failure rather than swallowing it, so a genuine
+ * problem (missing network, missing container) surfaces instead of
+ * silently leaving the container unable to reach its peer.
+ *
+ * @param network Network to connect the container to.
+ * @param container Name of the running container to attach.
+ * @throws If the docker command fails (network/container missing, etc.).
+ */
+export function connectNetwork(network, container) {
+    return dockerExec(["network", "connect", network, container]);
+}
+/**
+ * Force-remove a container by name. Default `allowFailure: true` because
+ * "remove if it exists" is the common idempotent-cleanup intent.
+ */
+export function removeContainer(name, options = { allowFailure: true }) {
+    return dockerExec(["rm", "-f", name], options);
+}
+/** Send `docker stop` to a container. Ignores already-stopped/missing containers. */
+export function stopContainer(name) {
+    return dockerExec(["stop", name], { allowFailure: true });
+}
+/**
+ * Run a docker CLI command with the parent process's stdin/stdout/
+ * stderr inherited, blocking until the child exits. Used by
+ * subcommands that hand the user's terminal to a foreground docker
+ * process (`familiar psql`'s psql shell, `familiar mcp call`'s
+ * one-shot CLI invocations against an MCP runtime container).
+ *
+ * Returns the child's exit status — `null`-on-signal collapses to
+ * 1 so the caller's `process.exit(...)` always sees a usable
+ * number. A failure to launch docker itself (e.g. binary missing)
+ * surfaces as a thrown {@link Error} the caller can format.
+ *
+ * @throws If the docker binary couldn't be spawned at all.
+ */
+export function dockerInteractive(args) {
+    const result = spawnSync("docker", [...args], { stdio: "inherit" });
+    if (result.error) {
+        throw new Error(`failed to launch docker: ${result.error.message}`);
+    }
+    return result.status ?? 1;
+}
+/**
+ * On Linux, `host.docker.internal` isn't built-in and must be mapped to
+ * the host gateway explicitly. macOS and Windows resolve it natively.
+ *
+ * Used by sidecars that dial a host-side listener (the bastion bridge,
+ * the tailscale plugin's serve proxy to the webserver).
+ *
+ * @returns Extra `docker run` args, or an empty array on macOS/Windows.
+ */
+export function hostGatewayArgs() {
+    if (os.platform() === "linux") {
+        return ["--add-host=host.docker.internal:host-gateway"];
+    }
+    return [];
+}

package/build/Plugin.d.ts

@@ -2,7 +2,7 @@ import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { CommandDef } from "citty";
 import type { AgentRunRow } from "./AgentRun.js";
 import type { CalendarApi } from "./Calendar.js";
-import type { ChatFilter } from "./ChatMessage.js";
+import type { ChatFilter, ChatHistoryQuery, ChatMessage } from "./ChatMessage.js";
 import type { ChatHandler, ChatUnsubscribe } from "./ChatMessageBus.js";
 import type { ConfigService } from "./Config.js";
 import type { EventFile, EventRow, NewEvent } from "./Event.js";
@@ -10,10 +10,14 @@ import type { Logger } from "./logging/Logger.js";
 import type { MailApi } from "./Mail.js";
 import type { MailStyleTemplate } from "./MailStyleTemplate.js";
 import type { ModelMetaData, ModelProviderDescriptor } from "./ModelMetaData.js";
+import type { ScratchFile } from "./Scratch.js";
 import type { StepResultRow } from "./StepResult.js";
 import type { StorageApi } from "./Storage.js";
 import type { ToolLevel } from "./ToolLevel.js";
 import type { ToolRunContext } from "./ToolRunner.js";
+import type { WebApi, WebUi } from "./WebAuth.js";
+import type { WebMenuContribution } from "./WebMenu.js";
+import type { WebPluginUi } from "./WebPlugin.js";
 import type { WorkspaceWatcherApi } from "./WorkspaceFile.js";
 export type { ChatHandler, Client as McpClient };
 /**
@@ -234,6 +238,25 @@ export interface HostContext {
          * can deadlock the input-event watcher's claim.
          */
         appendAssistantMessage(eventId: string, text: string): Promise<void>;
+        /**
+         * Insert a chatmessage of either role attached to `eventId`, for
+         * recording a conversation that happened outside the agent — e.g.
+         * the transcript of a voice call. Channel is resolved via the
+         * event's `preferred_chat_channel_id`. The same rule as for
+         * {@link appendAssistantMessage} applies: only for events that
+         * are already settled — typically a record-only event emitted
+         * with `state: "done"`, which no handler ever runs for.
+         */
+        appendMessage(eventId: string, role: "user" | "assistant", text: string): Promise<void>;
+        /**
+         * Read one page of a channel's history (both roles), oldest first:
+         * the newest `limit` messages before `beforeId`. For chat UIs that
+         * show scrollback; the same per-channel history the model sees for
+         * that channel's chat events.
+         *
+         * @throws {Error} When `limit` is outside 1 … `MAX_CHAT_HISTORY_PAGE`.
+         */
+        listMessages(query: ChatHistoryQuery): Promise<readonly ChatMessage[]>;
     };
     /**
      * Per-event scratch directory operations. Each event the bus
@@ -262,6 +285,23 @@ export interface HostContext {
          * caller is responsible for unique names.
          */
         addFiles(eventId: string, files: readonly EventFile[]): Promise<readonly string[]>;
+        /**
+         * The regular files directly in `/scratch/<eventId>/` (no
+         * subdirectories), hidden ones included — filter them with
+         * `isHiddenScratchFile` before showing files to users. Sorted
+         * by name; empty when the folder does not exist.
+         *
+         * @throws {Error} When `eventId` is not a numeric event id.
+         */
+        listFiles(eventId: string): Promise<readonly ScratchFile[]>;
+        /**
+         * Host path of `/scratch/<eventId>/<name>`, for reading or
+         * streaming the file. The file may not exist.
+         *
+         * @throws {Error} When `eventId` is not a numeric event id or
+         *   `name` is not a plain basename (same rules as `addFiles`).
+         */
+        resolveFile(eventId: string, name: string): string;
     };
     /**
      * The pino-style {@link Logger} for the plugin. Use `.info` for the
@@ -271,6 +311,14 @@ export interface HostContext {
      * plugin doing anything.
      */
     readonly logger: Logger;
+    /**
+     * Whether the daemon runs in dev mode (`FAMILIAR_DEV=1`, set by the
+     * monorepo's `npm run dev` launcher). Lets plugins enable developer
+     * conveniences such as the web UI's hot module reloading.
+     */
+    readonly isDevMode: boolean;
+    /** Version of the running familiar host (the `@getfamiliar/host` package version, e.g. `0.4.2`). */
+    readonly familiarVersion: string;
     /**
      * Absolute host path of the project's `data/` directory.
      *
@@ -399,6 +447,14 @@ export interface HostContext {
      * which maps the user's configured mounts onto providers.
      */
     readonly storage: StorageApi;
+    /**
+     * Core webserver hooks. A plugin that fronts the webserver with its
+     * own reverse proxy registers it during **`prepare()`** via
+     * `ctx.web.registerTrustedProxy({ secret, userHeader })`, the same
+     * contract a user-configured `webserver.auth.trustedProxies` entry
+     * follows (see {@link WebApi}).
+     */
+    readonly web: WebApi;
     /**
      * Read the per-mailbox style template the user (or the
      * extract-style handler) wrote at `data/mail/templates/<mailbox>/<name>.json`.
@@ -694,6 +750,52 @@ export interface PluginHostManifest {
      * call.
      */
     tools?(ctx: HostContext): readonly PluginTool[];
+    /**
+     * Provide the web UI: return its root controller, a Hono app mounted
+     * at `/` of the core webserver, and optionally a renderer for the
+     * login-flow pages ({@link WebUi.renderAuthPage}). Called after `start()` resolves (at
+     * boot and after every restart), so closures over `start`-time state
+     * (e.g. a dev server) are safe; a restart swaps the controller
+     * without rebinding the socket.
+     *
+     * Authentication stays in the core: every request reaching the
+     * controller passed the auth middleware, `c.get("principal")` is the
+     * signed-in user. The core routes `/login`, `/login/:token` and
+     * `/logout` take precedence over the controller's routes; the core
+     * decides what they do and only lets the UI render their markup.
+     *
+     * When several plugins provide a UI, `webserver.uiPlugin` picks one;
+     * without any, the webserver serves a plain page asking to install
+     * one (e.g. `@getfamiliar/plugin-web-ui`).
+     *
+     * Synchronous, side-effect-free: just build and return the app.
+     */
+    webUi?(ctx: HostContext): WebUi;
+    /**
+     * Contribute items to the web UI's sidebar menu: direct links or
+     * collapsible groups with sub-entries (icon, label, routes), plus a
+     * weight positioning this plugin's items among the others. Called
+     * after `start()` (at boot and after every restart); a disabled
+     * plugin contributes nothing. The core validates the items (lucide
+     * icon id, non-empty labels, routes starting with `/`) and disables
+     * the plugin in phase `webMenu` when they are malformed.
+     *
+     * Synchronous, side-effect-free: derive the items from constants and
+     * `ctx.config`.
+     */
+    webMenu?(ctx: HostContext): WebMenuContribution;
+    /**
+     * Serve HTTP routes and, optionally, a page in the web UI: return a
+     * controller (mounted at `/plugins/<plugin-id>/` behind the core
+     * authentication, concrete routes only, no catch-all) and an optional
+     * page module the web UI loads for browser routes under
+     * `/plugins/<plugin-id>` (see {@link WebPluginUi}). Called after
+     * `start()` (at boot and after every restart); a throw disables the
+     * plugin in phase `webPlugin`.
+     *
+     * Synchronous, side-effect-free: just build and return.
+     */
+    webPlugin?(ctx: HostContext): WebPluginUi;
     /**
      * Supply {@link ModelMetaData} for a model the default (models.dev)
      * database does not cover. The host calls this on every plugin that