@abot-ai/runtime 1.1.0 → 1.3.0

package/dist/src/web-ui/server.js

@@ -6,9 +6,11 @@ import { pathToFileURL } from "node:url";
 import { WebSocketServer } from "ws";
 import { inspectRuntimeConfigFileWithMeta } from "../runtime/config/loader.js";
 import { loadDotEnvFile } from "../shared/load-dotenv.js";
+import { createWebUiShutdown } from "./server-shutdown.js";
 import { ExternalBridgeWebBackend } from "./external-bridge-backend.js";
 import { LocalRuntimeWebBackend } from "./local-runtime-backend.js";
 import { resolveWebUiAddress } from "./web-ui-address.js";
+import { createLinkPreviewRouteHandler } from "./link-preview/routes.js";
 const DEFAULT_WEB_BACKEND = "runtime";
 const DEFAULT_BRIDGE_API_BASE = "http://127.0.0.1:8787/abot/api";
 const DEFAULT_BRIDGE_REALTIME_URL = "ws://127.0.0.1:8787/abot/realtime";
@@ -226,8 +228,11 @@ export function startWebUiServer(overrides = {}) {
             externalBridgeBackend.handleRealtimeConnection(client);
         });
     }
+    const handleLinkPreview = createLinkPreviewRouteHandler();
     const server = createServer((req, res) => {
         void (async () => {
+            if (await handleLinkPreview(req, res))
+                return;
             const pathname = new URL(req.url || "/", "http://localhost").pathname;
             if (pathname === "/web-config") {
                 sendJson(res, 200, {
@@ -301,7 +306,12 @@ export function startWebUiServer(overrides = {}) {
             wss.emit("connection", ws, req);
         });
     });
-    server.listen(options.port, options.host, () => {
+    const listenAbort = new AbortController();
+    server.listen({
+        port: options.port,
+        host: options.host,
+        signal: listenAbort.signal,
+    }, () => {
         console.log(`abot web UI listening on http://${options.host}:${options.port}`);
         if (localRuntimeBackend) {
             console.log("using local abot backend");
@@ -311,16 +321,9 @@ export function startWebUiServer(overrides = {}) {
             console.log(`using external bridge realtime ${options.realtimeUrl}`);
         }
     });
+    const schedulerStartup = localRuntimeBackend?.start(options.environments.map(({ id }) => id));
     return {
-        close: () => new Promise((resolveClose, reject) => {
-            wss.close();
-            server.close((error) => {
-                if (error)
-                    reject(error);
-                else
-                    resolveClose();
-            });
-        }),
+        close: createWebUiShutdown(server, wss, schedulerStartup, () => localRuntimeBackend?.stop(), listenAbort),
     };
 }
 const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";

package/dist/src/web-ui/session-read-state/availability.d.ts

@@ -0,0 +1,16 @@
+/** Isolate UI sidecar failures; canonical session operations stay outside this boundary. */
+export declare function captureReadStateAvailability<T>(operation: () => Promise<T>): Promise<{
+    readStateStatus: "available";
+    value: Awaited<T>;
+} | {
+    readStateStatus: "unavailable";
+    value?: undefined;
+}>;
+export declare function unavailableSessionReadState(sessionId: string): {
+    sessionId: string;
+    readStateStatus: "unavailable";
+    unreadCount: null;
+    hasUnread: null;
+    lastReadAt: null;
+    lastReadMessageId: null;
+};

package/dist/src/web-ui/session-read-state/availability.js

@@ -0,0 +1,20 @@
+/** Isolate UI sidecar failures; canonical session operations stay outside this boundary. */
+export async function captureReadStateAvailability(operation) {
+    try {
+        return { readStateStatus: "available", value: await operation() };
+    }
+    catch (error) {
+        console.error("Web UI read tracking unavailable:", error);
+        return { readStateStatus: "unavailable" };
+    }
+}
+export function unavailableSessionReadState(sessionId) {
+    return {
+        sessionId,
+        readStateStatus: "unavailable",
+        unreadCount: null,
+        hasUnread: null,
+        lastReadAt: null,
+        lastReadMessageId: null,
+    };
+}

package/dist/src/web-ui/session-read-state/projection.d.ts

@@ -0,0 +1,17 @@
+import type { SessionSnapshotMessage } from "../../sessions/types.js";
+import type { WebReadState } from "./store.js";
+export type ReadBoundary = {
+    readThroughMessageId?: unknown;
+    readThroughRequestId?: unknown;
+};
+export declare function advanceReadCursor(state: WebReadState, sessionId: string, messages: SessionSnapshotMessage[], boundary: ReadBoundary, now: number): void;
+export declare function projectSessionReadState(state: WebReadState, sessionId: string, messages: SessionSnapshotMessage[]): {
+    sessionId: string;
+    readStateStatus: "available";
+    unreadCount: number;
+    hasUnread: boolean;
+    lastReadMessageId: string | null;
+    lastReadAt: number;
+    latestMessageId: string | number | null;
+    latestAssistantMessageId: string | number | null;
+};

package/dist/src/web-ui/session-read-state/projection.js

@@ -0,0 +1,71 @@
+function messageTimestamp(message) {
+    const value = typeof message.createdAt === "number"
+        ? message.createdAt
+        : Date.parse(String(message.createdAt));
+    return Number.isFinite(value) ? value : 0;
+}
+function cursorIndex(messages, cursor) {
+    if (!cursor)
+        return -1;
+    if (!cursor.messageId)
+        return -1;
+    return messages.findIndex((message) => String(message.id) === cursor.messageId &&
+        messageTimestamp(message) === cursor.createdAt);
+}
+function requestedAssistantIndex(messages, boundary) {
+    const id = boundary.readThroughMessageId;
+    const hasNumericBoundary = typeof id === "number" && Number.isSafeInteger(id) && id >= 0;
+    if (hasNumericBoundary)
+        return messages.findIndex((message) => message.role === "assistant" && String(message.id) === String(id));
+    const requestId = boundary.readThroughRequestId;
+    if (typeof requestId !== "string" || !requestId)
+        return -1;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message.role === "assistant" && message.requestId === requestId)
+            return index;
+    }
+    return -1;
+}
+export function advanceReadCursor(state, sessionId, messages, boundary, now) {
+    const nextIndex = requestedAssistantIndex(messages, boundary);
+    if (nextIndex < 0)
+        return;
+    const cursors = new Map(state.cursors);
+    const previous = cursors.get(sessionId);
+    const previousIndex = cursorIndex(messages, previous);
+    if (previousIndex >= nextIndex)
+        return;
+    const message = messages[nextIndex];
+    const createdAt = messageTimestamp(message);
+    if (previous && previous.createdAt > createdAt)
+        return;
+    cursors.set(sessionId, {
+        messageId: String(message.id),
+        createdAt,
+        lastReadAt: Math.max(now, (previous?.lastReadAt ?? state.initializedAt) + 1),
+    });
+    state.cursors = [...cursors];
+}
+export function projectSessionReadState(state, sessionId, messages) {
+    const cursor = new Map(state.cursors).get(sessionId);
+    const readIndex = cursorIndex(messages, cursor);
+    const unreadCount = messages.filter((message, index) => {
+        if (message.role !== "assistant")
+            return false;
+        if (messageTimestamp(message) <= state.initializedAt)
+            return false;
+        return index > readIndex;
+    }).length;
+    return {
+        sessionId,
+        readStateStatus: "available",
+        unreadCount,
+        hasUnread: unreadCount > 0,
+        lastReadMessageId: cursor?.messageId || null,
+        lastReadAt: cursor?.lastReadAt ?? state.initializedAt,
+        latestMessageId: messages.at(-1)?.id ?? null,
+        latestAssistantMessageId: [...messages].reverse().find((message) => message.role === "assistant")
+            ?.id ?? null,
+    };
+}

package/dist/src/web-ui/session-read-state/service.d.ts

@@ -0,0 +1,86 @@
+import type { RuntimeConfig, SessionStore } from "../../runtime/ports.js";
+import type { SessionSnapshot } from "../../sessions/types.js";
+import { type ReadBoundary } from "./projection.js";
+type Sessions = Pick<SessionStore, "getSessionSnapshot">;
+type Environment = {
+    services: {
+        config: RuntimeConfig;
+        sessions: Sessions;
+    };
+};
+export declare class WebSessionReadStates {
+    private readonly getEnvironment;
+    private readonly now;
+    private readonly stores;
+    private readonly initializedAt;
+    constructor(getEnvironment: (id: string) => Environment, now?: () => number);
+    private store;
+    initialize(environmentId: string): Promise<void>;
+    forget(environmentId: string, sessionId: string): Promise<void>;
+    reset(environmentId: string, sessionId: string): Promise<void>;
+    project(environmentId: string, snapshot: SessionSnapshot): Promise<{
+        sessionId: string;
+        readStateStatus: "unavailable";
+        unreadCount: null;
+        hasUnread: null;
+        lastReadAt: null;
+        lastReadMessageId: null;
+    } | {
+        sessionId: string;
+        readStateStatus: "available";
+        unreadCount: number;
+        hasUnread: boolean;
+        lastReadMessageId: string | null;
+        lastReadAt: number;
+        latestMessageId: string | number | null;
+        latestAssistantMessageId: string | number | null;
+    }>;
+    mark(environmentId: string, sessionId: string, boundary: ReadBoundary): Promise<{
+        sessionId: string;
+        readStateStatus: "available";
+        unreadCount: number;
+        hasUnread: boolean;
+        lastReadMessageId: string | null;
+        lastReadAt: number;
+        latestMessageId: string | number | null;
+        latestAssistantMessageId: string | number | null;
+    } | null>;
+    list(environmentId: string): Promise<{
+        sessions: {
+            sessionId: string;
+            readStateStatus: "available";
+            unreadCount: number;
+            hasUnread: boolean;
+            lastReadMessageId: string | null;
+            lastReadAt: number;
+            latestMessageId: string | number | null;
+            latestAssistantMessageId: string | number | null;
+            id: string;
+            title: string;
+            createdAt: number;
+            updatedAt: number;
+            lastMessagePreview: string;
+            lastMessageAt: number | null;
+        }[];
+        nextCursor: null;
+    } | {
+        sessions: {
+            sessionId: string;
+            readStateStatus: "unavailable";
+            unreadCount: null;
+            hasUnread: null;
+            lastReadAt: null;
+            lastReadMessageId: null;
+            id: string;
+            title: string;
+            createdAt: number;
+            updatedAt: number;
+            lastMessagePreview: string;
+            lastMessageAt: number | null;
+            latestMessageId: string | number | null;
+            latestAssistantMessageId: string | number | null;
+        }[];
+        nextCursor: null;
+    }>;
+}
+export {};

package/dist/src/web-ui/session-read-state/service.js

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { join, resolve } from "node:path";
+import { SessionService } from "../../sessions/session-service.js";
+import { clientVisibleMessages, toSessionListItem, toSnapshotMessage, } from "../../sessions/record/projection.js";
+import { WebReadStateStore } from "./store.js";
+import { captureReadStateAvailability, unavailableSessionReadState, } from "./availability.js";
+import { advanceReadCursor, projectSessionReadState, } from "./projection.js";
+export class WebSessionReadStates {
+    getEnvironment;
+    now;
+    stores = new Map();
+    initializedAt;
+    constructor(getEnvironment, now = Date.now) {
+        this.getEnvironment = getEnvironment;
+        this.now = now;
+        this.initializedAt = now();
+    }
+    store(environmentId) {
+        const { paths } = this.getEnvironment(environmentId).services.config;
+        const identity = JSON.stringify([
+            environmentId,
+            resolve(paths.sessionsDir),
+        ]);
+        const existing = this.stores.get(identity);
+        if (existing)
+            return existing;
+        const filename = createHash("sha256").update(identity).digest("hex") + ".json";
+        const store = new WebReadStateStore(join(paths.runtimeDir, "web-ui", "read-state", filename), this.initializedAt);
+        this.stores.set(identity, store);
+        return store;
+    }
+    initialize(environmentId) {
+        return this.store(environmentId).initialize();
+    }
+    async forget(environmentId, sessionId) {
+        await captureReadStateAvailability(() => this.store(environmentId).forget(sessionId));
+    }
+    async reset(environmentId, sessionId) {
+        await captureReadStateAvailability(() => this.store(environmentId).reset(sessionId, this.now()));
+    }
+    async project(environmentId, snapshot) {
+        const result = await captureReadStateAvailability(() => this.store(environmentId).transaction((state) => projectSessionReadState(state, snapshot.sessionId, snapshot.messages)));
+        if (result.readStateStatus === "unavailable")
+            return unavailableSessionReadState(snapshot.sessionId);
+        return result.value;
+    }
+    async mark(environmentId, sessionId, boundary) {
+        const store = this.store(environmentId);
+        await store.initialize();
+        const sessions = this.getEnvironment(environmentId).services.sessions;
+        return store.transaction(async (state) => {
+            const snapshot = await sessions.getSessionSnapshot(sessionId, {
+                includeRequests: false,
+            });
+            if (!snapshot)
+                return null;
+            advanceReadCursor(state, sessionId, snapshot.messages, boundary, this.now());
+            return projectSessionReadState(state, sessionId, snapshot.messages);
+        });
+    }
+    async list(environmentId) {
+        const { sessionsDir } = this.getEnvironment(environmentId).services.config.paths;
+        // One canonical disk enumeration avoids mutable offset pages and sending
+        // every request event across the managed Runtime's bounded RPC transport.
+        const records = await new SessionService({ sessionsDir }).getAllSessions();
+        const projectedSessions = records.map((record) => ({
+            summary: toSessionListItem(record),
+            messages: clientVisibleMessages(record.messages).map((message) => toSnapshotMessage(record.id, message, record.requests ?? [])),
+        }));
+        const result = await captureReadStateAvailability(() => this.store(environmentId).transaction((state) => {
+            const sessions = projectedSessions.map(({ summary, messages }) => {
+                return {
+                    ...summary,
+                    ...projectSessionReadState(state, summary.id, messages),
+                };
+            });
+            return { sessions, nextCursor: null };
+        }));
+        if (result.readStateStatus === "unavailable")
+            return {
+                sessions: projectedSessions.map(({ summary }) => ({
+                    ...summary,
+                    ...unavailableSessionReadState(summary.id),
+                })),
+                nextCursor: null,
+            };
+        return result.value;
+    }
+}

package/dist/src/web-ui/session-read-state/store.d.ts

@@ -0,0 +1,22 @@
+export type WebReadCursor = {
+    messageId: string;
+    createdAt: number;
+    lastReadAt: number;
+};
+export type WebReadState = {
+    version: 1;
+    initializedAt: number;
+    cursors: Array<[string, WebReadCursor]>;
+};
+/** UI-owned state; never writes Runtime session records or model context. */
+export declare class WebReadStateStore {
+    private readonly initializedAt;
+    private readonly path;
+    constructor(path: string, initializedAt: number);
+    private load;
+    private save;
+    transaction<T>(operation: (state: WebReadState) => T | Promise<T>): Promise<T>;
+    initialize(): Promise<void>;
+    reset(sessionId: string, now: number): Promise<void>;
+    forget(sessionId: string): Promise<void>;
+}

package/dist/src/web-ui/session-read-state/store.js

@@ -0,0 +1,110 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+const pendingWrites = new Map();
+function hasFileErrorCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function isReadCursor(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const cursor = value;
+    if (typeof cursor.messageId !== "string")
+        return false;
+    if (!Number.isFinite(cursor.createdAt))
+        return false;
+    return Number.isFinite(cursor.lastReadAt);
+}
+function decodeReadState(raw) {
+    const state = JSON.parse(raw);
+    if (state?.version !== 1)
+        throw new Error("Unsupported Web UI read state.");
+    if (!Number.isFinite(state.initializedAt))
+        throw new Error("Invalid Web UI read boundary.");
+    if (!Array.isArray(state.cursors))
+        throw new Error("Invalid Web UI read cursors.");
+    for (const entry of state.cursors) {
+        if (!Array.isArray(entry) || entry.length !== 2)
+            throw new Error("Invalid Web UI read cursor entry.");
+        if (typeof entry[0] !== "string" || !isReadCursor(entry[1]))
+            throw new Error("Invalid Web UI read cursor entry.");
+    }
+    return state;
+}
+/** UI-owned state; never writes Runtime session records or model context. */
+export class WebReadStateStore {
+    initializedAt;
+    path;
+    constructor(path, initializedAt) {
+        this.initializedAt = initializedAt;
+        this.path = resolve(path);
+    }
+    async load() {
+        try {
+            return decodeReadState(await readFile(this.path, "utf8"));
+        }
+        catch (error) {
+            if (hasFileErrorCode(error, "ENOENT"))
+                return null;
+            throw error;
+        }
+    }
+    async save(state) {
+        await mkdir(dirname(this.path), { recursive: true });
+        const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, JSON.stringify(state), "utf8");
+            await rename(temporary, this.path);
+        }
+        catch (error) {
+            await rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+    async transaction(operation) {
+        const prior = pendingWrites.get(this.path) ?? Promise.resolve();
+        const pending = prior
+            .catch(() => undefined)
+            .then(async () => {
+            const existing = await this.load();
+            const state = existing ?? {
+                version: 1,
+                initializedAt: this.initializedAt,
+                cursors: [],
+            };
+            const before = JSON.stringify(state);
+            const result = await operation(state);
+            if (!existing || JSON.stringify(state) !== before)
+                await this.save(state);
+            return result;
+        });
+        pendingWrites.set(this.path, pending);
+        try {
+            return await pending;
+        }
+        finally {
+            if (pendingWrites.get(this.path) === pending)
+                pendingWrites.delete(this.path);
+        }
+    }
+    initialize() {
+        return this.transaction(() => undefined);
+    }
+    reset(sessionId, now) {
+        return this.transaction((state) => {
+            const cursors = new Map(state.cursors);
+            const previous = cursors.get(sessionId);
+            cursors.set(sessionId, {
+                messageId: "",
+                createdAt: 0,
+                lastReadAt: Math.max(now, (previous?.lastReadAt ?? state.initializedAt) + 1),
+            });
+            state.cursors = [...cursors];
+        });
+    }
+    forget(sessionId) {
+        return this.transaction((state) => {
+            state.cursors = state.cursors.filter(([id]) => id !== sessionId);
+        });
+    }
+}

package/docs/configuration.md

@@ -31,11 +31,16 @@ AGENT_BRIDGE_TOKEN=
 LLM_RUNTIME_CONFIG_FILE=local/runtime.config.json
 ```
 
-`BRAVE_SEARCH_API_KEY` is optional for startup and URL fetching. The bundled
-Web plugin always exposes `web_fetch` and `web_search`; invoking `web_search`
-without a non-empty key returns a clear plugin configuration error without
-making a search request. The key never belongs in runtime JSON or a plugin
-manifest.
+`BRAVE_SEARCH_API_KEY` is optional. The bundled Web plugin always exposes
+`web_fetch` and `web_search`. A non-empty key selects Brave Search; without one,
+`web_search` uses Light search over a limited catalog of public Hebrew and
+English sources. Light reads those sources directly without an external search
+engine. A failing configured key does not silently switch providers. The key
+never belongs in runtime JSON or a plugin manifest.
+
+Light uses the Web plugin's defaults and an in-memory cache; no background
+crawler or separate service is installed. See
+[Known Limitations](known-limitations.md#web-search) for its coverage and limits.
 
 Provider configs should reference env var names:
 
@@ -138,7 +143,21 @@ storage, privacy, retrieval, and management behavior.
 
 ## Paths
 
-`environment.paths.runtimeDir` is environment-local generated runtime state.
+`environment.paths.runtimeDir` is the generated runtime state base. A named
+environment profile without its own `paths.runtimeDir` uses
+`<base>/environments/<sha256(profileId)>`. The stable profile ID determines that
+directory; changing models or adding another profile does not move its state.
+`LLM_RUNTIME_DIR` takes precedence over profile paths and acts as the shared base
+when a profile is selected. Without a selected profile, the existing runtime
+directory layout is unchanged.
+
+An explicit `environment.profiles.<id>.paths.runtimeDir` is already a final
+environment directory and is preserved when there is no `LLM_RUNTIME_DIR`
+override. Explicit session, attachment and trace path overrides also remain
+final paths. Use distinct final paths for different environments. The resolved
+runtime directory owns local hosting, scheduling, passive memory, plugin state,
+and the default session, attachment and log paths. Shared, compiled, workspace
+and agent-work directories retain their configured sharing behavior.
 `environment.paths.attachmentsDir` stores runtime-managed attachment files
 referenced by session/request metadata. Images and supported document files
 share this store; document contents are read on demand by a request-bound tool
@@ -215,6 +234,32 @@ LLM_RUNTIME_PROFILE=dev npm run dev
 
 The active profile id becomes the runtime id used by the bridge.
 
+Existing populated state in an inherited base is never automatically moved or
+silently replaced by an empty environment. Loading stops with
+`runtime_environment_storage_assignment_required` until that state is explicitly
+assigned. For example, to retain an existing `prod` environment at `.runtime`
+and add an isolated `dev` environment:
+
+```json
+{
+  "environment": {
+    "default": "prod",
+    "paths": { "runtimeDir": ".runtime" },
+    "profiles": {
+      "prod": { "paths": { "runtimeDir": ".runtime" } },
+      "dev": {}
+    }
+  }
+}
+```
+
+This leaves existing Jobs and conversations in place and gives `dev` its own
+namespace. Preserve any previous explicit session, attachment and trace paths
+on the assigned profile too. Remove a shared `LLM_RUNTIME_DIR` override before
+making this assignment because environment variables keep their precedence.
+The stored Jobs must retain their original environment ID. Empty state folders
+and intentionally shared or compiled artifacts do not require assignment.
+
 ## Request Runner
 
 The runtime config owns host wiring, installed models, and plugin availability.
@@ -310,10 +355,12 @@ the request-runner context block supplies only admission headroom.
 subtracted while projecting messages so the prompt does not consume the whole
 context window; it is never forwarded to a provider as an output limit. Model
 steps may vary their prompt contract, timeout, format, or other generation
-controls, but they do not receive a shared per-step output-token cap.
+controls, but configuration does not define a shared per-step output-token cap.
 The Ollama adapter still sends a finite provider-native `num_predict`, derived
-mechanically from the final provider input, the physical context remainder,
-and a strict bounded output schema when one applies.
+mechanically from the final provider input and the physical context remainder.
+Registered core-decision steps additionally retain their internal output-token
+limit. Output schema size does not impose another generation limit; schema
+projection, validation, input estimation, and compaction remain unchanged.
 
 The required context fields remain explicit. Unknown fields, unknown step ids,
 and invalid explicit overrides are rejected during configuration loading;

package/docs/installation.md

@@ -155,10 +155,13 @@ a bundled plugin: duplicate plugin ids fail closed.
 The passive long-term memory service belongs to the Runtime core and does not
 depend on the bundled `memory` plugin.
 
-Web URL fetching is available through the bundled Web plugin without a search
-credential. Set `BRAVE_SEARCH_API_KEY` to make `web_search` operational. With
-no key, `web_fetch` remains operational and a `web_search` invocation fails
-locally with a configuration error before any search request is made.
+The bundled Web plugin supports URL fetching and Light search without a search
+credential. Light searches a limited catalog of public Hebrew and English
+sources directly; it does not query an external search engine or provide
+whole-web coverage. Set `BRAVE_SEARCH_API_KEY` to use Brave Search instead.
+A configured Brave key that fails remains a Brave error. See
+[Known Limitations](known-limitations.md#web-search) for Light's discovery and
+cache boundaries.
 
 ## Run From Source
 

package/docs/known-limitations.md

@@ -61,6 +61,27 @@ plugin entrypoints are not currently supported.
 Plugin behavior belongs inside the plugin. Runtime orchestration should only
 see the generic selected catalog and execution results.
 
+## Web Search
+
+With a configured `BRAVE_SEARCH_API_KEY`, `web_search` uses Brave Search and
+preserves its authentication and rate-limit errors. Without a key, Light search
+discovers and ranks pages within a catalog of public Hebrew and English
+sources. It contacts content sources directly, without another search engine.
+
+Light does not maintain a whole-web index. Its source selection, crawl depth,
+candidate count, response sizes, and request deadline are bounded. Results may
+be partial because a source is unavailable, disallows crawling, or exceeds a
+budget. Zero matches mean no matches in the inspected sources, not that the
+information is absent from the web. Source coverage accompanies the results.
+
+The document cache exists only in the plugin instance's memory, bounded to
+16 MiB of serialized content and 500 documents. Feed entries expire within
+five minutes and page entries within 30 minutes; origin directives can shorten
+these lifetimes. Restarting the runtime clears the cache. There is no background
+crawl, browser rendering, or persistent search database. Content that requires
+JavaScript may therefore be unavailable. Exact public URL fetching remains a
+separate `web_fetch` capability with its existing public-network restrictions.
+
 ## Passive Long-Term Memory
 
 Passive long-term memory is disabled by default and requires an embedding model