@frockbot/plugin-search 0.0.0 → 0.1.1

package/src/bot.ts

@@ -0,0 +1,125 @@
+// The Bot half of the Search Package: the projection, and the sink it writes to.
+//
+// The kernel imports no Package, so nothing here is called from `kernel-do`.
+// The Bot Durable Object projects a *settled* run — one that has already
+// reached a durable terminal state — through the narrow `SearchSinkV1` binding
+// its host constructs, exactly as the Memory Package reaches the User Durable
+// Object through `MEMORY_PROJECTS` (`plugin-shell/src/backend-memory.ts`).
+//
+// Projection happens after settlement, never before it, so a failed index
+// write loses nothing: the run is already durable in the Bot Durable Object,
+// and `rebuildSearchIndex` reconstructs every row this call would have made.
+import { boundSearchBodyV1, type SearchRowV1 } from "./shared.js";
+
+/**
+ * The User-scoped index, as a Bot Durable Object calls it.
+ *
+ * `indexRows` is idempotent on `(botId, runId, seq)`, which is what lets the
+ * caller treat it as fire-and-forget: a retried Turn, a resumed Turn, and a
+ * rebuild all converge on the same rows.
+ */
+export interface SearchSinkV1 {
+  indexRows(rows: readonly SearchRowV1[]): Promise<void>;
+}
+
+/**
+ * The decoded run projection this Package reads.
+ *
+ * Structural on purpose: it is satisfied by both the wire `ClientRunV1` the
+ * Shell Package emits and the `ClientRun` its decoder returns, so the rows a
+ * Turn writes on settlement and the rows a rebuild reads back out of the run
+ * list come from one function rather than two that must agree.
+ */
+export interface SearchProjectableRunV1 {
+  runId: string;
+  admittedAt?: string;
+  input: string;
+  status:
+    | "running"
+    | "completed"
+    | "failed"
+    | "cancelled"
+    | "reconciliation-required";
+  events: readonly {
+    type: string;
+    call?: { id: string; name: string };
+    callId?: string;
+    content?: string;
+  }[];
+  /**
+   * The settled assistant text. The wire DTO carries it as
+   * `outcome.text` and the decoded client value as `responseText`; both are
+   * read here so a Turn's settlement-time projection and a rebuild's cannot
+   * diverge on which shape they happened to be handed.
+   */
+  responseText?: string;
+  outcome?: { type: string; text?: string };
+}
+
+function assistantText(run: SearchProjectableRunV1): string | undefined {
+  if (run.responseText !== undefined) return run.responseText;
+  return run.outcome?.type === "completed" ? run.outcome.text : undefined;
+}
+
+/** A run is projected once it can no longer change. */
+export function isSettledSearchRunV1(run: {
+  status: SearchProjectableRunV1["status"];
+}): boolean {
+  return (
+    run.status === "completed" ||
+    run.status === "failed" ||
+    run.status === "cancelled"
+  );
+}
+
+/**
+ * The rows one settled run contributes, in a deterministic order.
+ *
+ * Determinism is the whole contract: `seq` is derived from the run's own
+ * projection and from nothing else, so the rows a Turn writes on settlement
+ * and the rows a rebuild writes months later are byte-for-byte identical, and
+ * re-projecting a run is a no-op rather than a duplicate.
+ *
+ * Body text only. Never a model request, never the Composition snapshot, never
+ * Memory — Memory has its own search, and a request is not conversation.
+ */
+export function searchRowsFromClientRunV1(
+  botId: string,
+  run: SearchProjectableRunV1,
+): SearchRowV1[] {
+  // A run with no admission time cannot be ordered against the others, and the
+  // index orders by it; a row it cannot place is one it does not keep.
+  if (!isSettledSearchRunV1(run) || !run.admittedAt) return [];
+  const rows: SearchRowV1[] = [];
+  const at = run.admittedAt;
+  const push = (kind: SearchRowV1["kind"], body: string): void => {
+    const bounded = boundSearchBodyV1(body).trim();
+    if (bounded.length === 0) return;
+    rows.push({
+      botId,
+      runId: run.runId,
+      seq: rows.length,
+      kind,
+      at,
+      body: bounded,
+    });
+  };
+  push("user", run.input);
+  // Tool text is indexed but excluded from default results: a tool result can
+  // carry credentials-adjacent output, so reading it back is an explicit
+  // `kinds` opt-in rather than something a stray query surfaces.
+  const results = new Map<string, string>();
+  for (const event of run.events) {
+    if (event.type === "tool/result" && event.callId) {
+      results.set(event.callId, event.content ?? "");
+    }
+  }
+  for (const event of run.events) {
+    if (event.type !== "tool/call" || !event.call) continue;
+    const result = results.get(event.call.id);
+    push("tool", result ? `${event.call.name}\n${result}` : event.call.name);
+  }
+  const answer = run.status === "completed" ? assistantText(run) : undefined;
+  if (answer) push("assistant", answer);
+  return rows;
+}

package/src/client/SearchBox.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import { UiIcon } from "@frockbot/client-ui";
+import { inject } from "vue";
+import { searchWebDataKey } from "./state.js";
+
+const provided = inject(searchWebDataKey);
+if (!provided) throw new Error("Search client data was not provided");
+const search = provided;
+</script>
+
+<template>
+  <button
+    type="button"
+    class="search-box"
+    aria-label="Search every Bot's conversations"
+    @click="search.open()"
+  >
+    <UiIcon name="search" size="sm" />
+    <span class="search-box-label">Search</span>
+  </button>
+</template>

package/src/client/SearchOverlay.vue

@@ -0,0 +1,165 @@
+<script setup lang="ts">
+/**
+ * Search across every Bot this User has.
+ *
+ * Every state is explicit and named: nothing typed yet, nothing found,
+ * rebuilding, and a truncated index. A blank panel that could mean any of the
+ * four is the one outcome this surface must never produce.
+ */
+import { UiIcon, UiIconButton } from "@frockbot/client-ui";
+import { computed, nextTick, onBeforeUnmount, ref, watch } from "vue";
+import { inject } from "vue";
+import { searchWebDataKey } from "./state.js";
+
+const provided = inject(searchWebDataKey);
+if (!provided) throw new Error("Search client data was not provided");
+const search = provided;
+
+const input = ref<HTMLInputElement>();
+const DEBOUNCE_MS = 200;
+let debounce: ReturnType<typeof setTimeout> | undefined;
+
+void nextTick(() => input.value?.focus());
+watch(
+  () => search.value.query,
+  () => {
+    if (debounce) clearTimeout(debounce);
+    debounce = setTimeout(() => void search.value.run(), DEBOUNCE_MS);
+  },
+);
+onBeforeUnmount(() => {
+  if (debounce) clearTimeout(debounce);
+});
+
+const results = computed(() => search.value.results);
+const hasQuery = computed(() => search.value.query.trim().length > 0);
+const groups = computed(() => results.value?.groups ?? []);
+const totalHits = computed(() =>
+  groups.value.reduce((sum, group) => sum + group.totalHits, 0),
+);
+
+function monogram(name: string): string {
+  return [...name.trim()][0]?.toUpperCase() ?? "?";
+}
+
+function kindLabel(kind: string): string {
+  if (kind === "user") return "You";
+  if (kind === "assistant") return "Reply";
+  if (kind === "tool") return "Tool";
+  return "Media";
+}
+
+function whenLabel(at: string): string {
+  const value = new Date(at);
+  return Number.isFinite(value.getTime()) ? value.toLocaleDateString() : "";
+}
+</script>
+
+<template>
+  <div class="search-surface">
+    <div class="search-input-row">
+      <UiIcon name="search" size="sm" />
+      <input
+        ref="input"
+        class="search-input"
+        type="search"
+        placeholder="Search every Bot's conversations"
+        aria-label="Search query"
+        :value="search.query"
+        @input="search.setQuery(($event.target as HTMLInputElement).value)"
+      />
+    </div>
+
+    <div class="search-filters">
+      <label class="search-filter">
+        <input
+          type="checkbox"
+          :checked="search.includeArchived"
+          @change="
+            search.setIncludeArchived(
+              ($event.target as HTMLInputElement).checked,
+            )
+          "
+        />
+        Archived Bots
+      </label>
+      <label class="search-filter">
+        <input
+          type="checkbox"
+          :checked="search.includeTools"
+          @change="
+            search.setIncludeTools(($event.target as HTMLInputElement).checked)
+          "
+        />
+        Tool output
+      </label>
+      <UiIconButton
+        class="search-rebuild"
+        icon="refresh"
+        label="Rebuild the search index"
+        size="sm"
+        :disabled="search.rebuilding"
+        @click="search.rebuild()"
+      />
+    </div>
+
+    <!--
+      The index is a projection, so a truncated or rebuilding one is reported
+      rather than quietly answering with less than it holds.
+    -->
+    <p v-if="search.indexState === 'rebuilding'" class="search-note">
+      Rebuilding the index from every Bot's stored turns. Results are incomplete
+      until it finishes.
+    </p>
+    <p v-else-if="search.indexState === 'truncated'" class="search-note">
+      This index reached its size limit, so the oldest turns were dropped.
+      Rebuilding will not bring them back.
+    </p>
+    <p v-if="search.error" class="search-error" role="alert">
+      {{ search.error }}
+    </p>
+
+    <p v-if="!hasQuery" class="search-empty">
+      Type to search every conversation this account has.
+    </p>
+    <p v-else-if="search.loading && !results" class="search-empty">
+      Searching…
+    </p>
+    <p v-else-if="results && totalHits === 0" class="search-empty">
+      No turns match “{{ results.query }}”.
+    </p>
+
+    <ol v-else-if="results" class="search-groups">
+      <li v-for="group in groups" :key="group.botId" class="search-group">
+        <div class="search-group-head">
+          <span class="search-group-avatar search-group-monogram">{{
+            monogram(group.botName)
+          }}</span>
+          <span class="search-group-name">{{ group.botName }}</span>
+          <span v-if="group.archived" class="search-tag">Archived</span>
+          <span v-else-if="group.hidden" class="search-tag">Hidden</span>
+          <span class="search-group-count">{{ group.totalHits }}</span>
+        </div>
+        <ol class="search-hits">
+          <li v-for="hit in group.hits" :key="`${hit.runId}-${hit.snippet}`">
+            <button
+              type="button"
+              class="search-hit"
+              @click="search.openHit(group.botId, hit.runId, hit.deepLink)"
+            >
+              <span class="search-hit-meta">
+                <span class="search-hit-kind">{{ kindLabel(hit.kind) }}</span>
+                <span class="search-hit-when">{{ whenLabel(hit.at) }}</span>
+              </span>
+              <span class="search-hit-snippet">{{ hit.snippet }}</span>
+            </button>
+          </li>
+        </ol>
+      </li>
+    </ol>
+
+    <p v-if="results?.page.truncated" class="search-note">
+      More matches than this page holds. Narrow the query to see them.
+    </p>
+  </div>
+</template>

package/src/client/index.ts

@@ -0,0 +1,192 @@
+// The Search Package's hosted client Contribution.
+//
+// It registers one surface on the shell's surface registry, one header
+// control, and one keyboard shortcut. Everything it renders comes from
+// `GET /api/search`, decoded at the seam; the client holds no index and
+// assembles no deep link of its own.
+import {
+  clientSurfaceRegistryKey,
+  type ClientPlugin,
+} from "@frockbot/client-core";
+import { frockBotWebDataKey } from "@frockbot/plugin-shell/shared";
+import { ref } from "vue";
+import {
+  decodeClientSearchRebuildReceiptV1,
+  decodeClientSearchResultsV1,
+  searchTurnAnchorV1,
+  SEARCH_MAX_QUERY_LENGTH_V1,
+} from "../shared.js";
+import SearchBox from "./SearchBox.vue";
+import SearchOverlay from "./SearchOverlay.vue";
+import {
+  searchKindsV1,
+  searchWebDataKey,
+  type SearchWebData,
+} from "./state.js";
+import "./styles.css";
+
+export const SEARCH_SURFACE_ID = "search";
+
+/**
+ * How long the overlay waits for a deep-linked turn to render.
+ *
+ * A hit can name a Turn further back than the conversation's newest page, so
+ * the anchor may never appear. Waiting a bounded moment and then leaving the
+ * reader on the right Bot is the honest outcome; pretending to scroll is not.
+ */
+const ANCHOR_TIMEOUT_MS = 4_000;
+const ANCHOR_POLL_MS = 100;
+
+async function scrollToTurn(runId: string): Promise<boolean> {
+  if (typeof document === "undefined") return false;
+  const anchor = searchTurnAnchorV1(runId);
+  const deadline = Date.now() + ANCHOR_TIMEOUT_MS;
+  for (;;) {
+    const element = document.getElementById(anchor);
+    if (element) {
+      element.scrollIntoView({ block: "center", behavior: "smooth" });
+      return true;
+    }
+    if (Date.now() >= deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, ANCHOR_POLL_MS));
+  }
+}
+
+export const searchClientPlugin: ClientPlugin = (ctx) => {
+  if (!ctx.transport.hostedRequest) {
+    throw new Error("Search hosted transport is unavailable");
+  }
+  const request = ctx.transport.hostedRequest.bind(ctx.transport);
+  const surfaces = ctx.inject(clientSurfaceRegistryKey);
+  const shell = ctx.inject(frockBotWebDataKey);
+  let queryGeneration = 0;
+
+  const state = ref<SearchWebData>({
+    query: "",
+    loading: false,
+    rebuilding: false,
+    includeArchived: false,
+    includeTools: false,
+    indexState: "ready",
+    setQuery(value) {
+      state.value.query = value.slice(0, SEARCH_MAX_QUERY_LENGTH_V1);
+    },
+    setIncludeArchived(value) {
+      state.value.includeArchived = value;
+      void state.value.run();
+    },
+    setIncludeTools(value) {
+      state.value.includeTools = value;
+      void state.value.run();
+    },
+    async run() {
+      const generation = ++queryGeneration;
+      const query = state.value.query.trim();
+      if (!query) {
+        state.value.results = undefined;
+        state.value.loading = false;
+        state.value.error = undefined;
+        return;
+      }
+      state.value.loading = true;
+      state.value.error = undefined;
+      try {
+        const params = new URLSearchParams({ q: query });
+        params.set("kinds", searchKindsV1(state.value.includeTools).join(","));
+        if (state.value.includeArchived) params.set("includeArchived", "true");
+        const results = decodeClientSearchResultsV1(
+          await request(`/api/search?${params.toString()}`),
+        );
+        // A slower earlier query must never overwrite a newer answer.
+        if (generation !== queryGeneration) return;
+        state.value.results = results;
+        state.value.indexState = results.indexState;
+      } catch (error) {
+        if (generation !== queryGeneration) return;
+        state.value.error =
+          error instanceof Error ? error.message : "Search failed";
+      } finally {
+        if (generation === queryGeneration) state.value.loading = false;
+      }
+    },
+    async rebuild() {
+      state.value.rebuilding = true;
+      state.value.indexState = "rebuilding";
+      state.value.error = undefined;
+      try {
+        const receipt = decodeClientSearchRebuildReceiptV1(
+          await request("/api/search/rebuild", "POST", "{}"),
+        );
+        state.value.indexState = receipt.indexState;
+        await state.value.run();
+      } catch (error) {
+        state.value.error =
+          error instanceof Error ? error.message : "Rebuild failed";
+      } finally {
+        state.value.rebuilding = false;
+      }
+    },
+    async openHit(botId, runId, deepLink) {
+      surfaces.close();
+      try {
+        if (shell.value.activeBotId !== botId) {
+          await shell.value.selectBot(botId);
+        }
+        // The link is the real URL the route handed back, so a reader can copy
+        // it, and a reload lands on the same Bot and the same anchor.
+        if (typeof window !== "undefined") {
+          window.history.replaceState(
+            window.history.state,
+            "",
+            new URL(deepLink, window.location.href),
+          );
+        }
+        if (!(await scrollToTurn(runId))) {
+          state.value.error =
+            "That turn is further back than the loaded conversation; scroll up to reach it.";
+        }
+      } catch (error) {
+        state.value.error =
+          error instanceof Error ? error.message : "Could not open that turn";
+      }
+    },
+    open() {
+      surfaces.open(SEARCH_SURFACE_ID);
+    },
+    close() {
+      surfaces.close();
+    },
+  });
+
+  const onKeydown = (event: KeyboardEvent): void => {
+    if (event.key !== "k" && event.key !== "K") return;
+    if (!event.metaKey && !event.ctrlKey) return;
+    if (event.altKey) return;
+    event.preventDefault();
+    state.value.open();
+  };
+  if (typeof window !== "undefined") {
+    window.addEventListener("keydown", onKeydown);
+  }
+
+  return [
+    ctx.provide(searchWebDataKey, state),
+    surfaces.register({
+      id: SEARCH_SURFACE_ID,
+      title: "Search",
+      component: SearchOverlay,
+    }),
+    ctx.slot({
+      slot: "frockbot.sidebar-top",
+      order: 10,
+      component: SearchBox,
+    }),
+    () => {
+      if (typeof window !== "undefined") {
+        window.removeEventListener("keydown", onKeydown);
+      }
+    },
+  ];
+};
+
+export default searchClientPlugin;

package/src/client/state.ts

@@ -0,0 +1,44 @@
+import type { InjectionKey, Ref } from "vue";
+import type {
+  ClientSearchResultsV1,
+  SearchIndexStateV1,
+  SearchRowKindV1,
+} from "../shared.js";
+
+/**
+ * The Search surface's client state.
+ *
+ * It renders backend state and submits commands; it is not a second authority.
+ * The index state, the grouping, and every deep link come from the route, so
+ * the overlay never assembles one out of parts it might get wrong.
+ */
+export interface SearchWebData {
+  query: string;
+  /** Undefined until a query has been run at all: "empty" and "no results" differ. */
+  results?: ClientSearchResultsV1;
+  loading: boolean;
+  rebuilding: boolean;
+  error?: string;
+  includeArchived: boolean;
+  includeTools: boolean;
+  indexState: SearchIndexStateV1;
+  /** Runs the current query, debounced by the caller. */
+  run(): Promise<void>;
+  setQuery(value: string): void;
+  setIncludeArchived(value: boolean): void;
+  setIncludeTools(value: boolean): void;
+  /** Rebuilds the whole index from the Bots' own stored runs. */
+  rebuild(): Promise<void>;
+  /** Switches to the Bot and scrolls its conversation to the turn. */
+  openHit(botId: string, runId: string, deepLink: string): Promise<void>;
+  open(): void;
+  close(): void;
+}
+
+export function searchKindsV1(includeTools: boolean): SearchRowKindV1[] {
+  return includeTools ? ["user", "assistant", "tool"] : ["user", "assistant"];
+}
+
+export const searchWebDataKey: InjectionKey<Ref<SearchWebData>> = Symbol(
+  "frockbot-search-web-data",
+);