@frockbot/plugin-search 0.0.0 → 0.1.0

package/frockbot.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 3,
+  "id": "search",
+  "displayName": "Search",
+  "version": "0.0.1",
+  "compatibility": { "frockbot": ">=0.0.1" },
+  "dependencies": {
+    "flock": ">=0.0.1",
+    "shell": ">=0.0.1",
+    "ui-theme": ">=0.0.1"
+  },
+  "contributions": {
+    "backend": [
+      { "entry": "./user", "host": "user" },
+      { "entry": "./backend", "host": "gateway" }
+    ],
+    "client": {
+      "entry": "./client",
+      "mounts": [{ "slot": "frockbot.header-actions", "order": 10 }],
+      "outlets": []
+    }
+  },
+  "permissions": []
+}

package/package.json

@@ -1,14 +1,50 @@
 {
   "name": "@frockbot/plugin-search",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./backend": "./src/backend.ts",
+    "./bot": "./src/bot.ts",
+    "./client": "./src/client/index.ts",
+    "./frockbot.json": "./frockbot.json",
+    "./groups": "./src/groups.ts",
+    "./index-store": "./src/index-store.ts",
+    "./manifest": "./src/manifest.ts",
+    "./package.json": "./package.json",
+    "./shared": "./src/shared.ts",
+    "./testing": "./src/testing.ts",
+    "./user": "./src/user.ts"
+  },
+  "frockbot": {
+    "manifest": "./frockbot.json"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/client-core": "0.1.0",
+    "@frockbot/client-ui": "0.1.0",
+    "@frockbot/plugin-flock": "0.1.0",
+    "@frockbot/plugin-shell": "0.1.0",
+    "cordis": "4.0.0-rc.8",
+    "vue": "3.5.41"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "@vitejs/plugin-vue": "6.0.8",
+    "typescript": "5.9.3",
+    "vite": "8.2.2",
+    "vue-tsc": "3.3.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/plugin-search"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/backend.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createSearchBackendContribution,
+  decodeSearchRequestQueryV1,
+  type SearchGatewayHost,
+} from "./backend.ts";
+import {
+  decodeClientSearchRebuildReceiptV1,
+  decodeClientSearchResultsV1,
+  type SearchIndexResultsV1,
+  type SearchQueryV1,
+} from "./shared.ts";
+
+function url(search: string): URL {
+  return new URL(`https://frockbot.test/api/search${search}`);
+}
+
+function host(
+  overrides: Partial<SearchGatewayHost> = {},
+): SearchGatewayHost & { queries: SearchQueryV1[] } {
+  const queries: SearchQueryV1[] = [];
+  return {
+    queries,
+    async searchTranscripts(_userId, query) {
+      queries.push(query);
+      return {
+        schemaVersion: 1,
+        query: query.query,
+        hits: [
+          {
+            botId: "bot-a",
+            runId: "run-1",
+            kind: "user",
+            at: "2026-08-31T00:00:00.000Z",
+            snippet: "the gym build",
+          },
+        ],
+        truncated: false,
+        indexState: "ready",
+      } satisfies SearchIndexResultsV1;
+    },
+    async rebuildSearchIndex() {
+      return {
+        schemaVersion: 1,
+        status: "rebuilt",
+        indexedRows: 4,
+        bots: 2,
+        indexState: "ready",
+      };
+    },
+    async listBotIdentities() {
+      return {
+        schemaVersion: 1,
+        identities: [
+          {
+            schemaVersion: 1,
+            botId: "bot-a",
+            name: "Site foreman",
+            namedBy: "user",
+            hiddenFromSidebar: false,
+          },
+        ],
+      };
+    },
+    async listBotLifecycles() {
+      return { schemaVersion: 1, lifecycles: [] };
+    },
+    ...overrides,
+  };
+}
+
+const CONTEXT = { userId: "user-1", client: "browser" as const };
+
+describe("the search query string", () => {
+  test("round-trips every accepted parameter into the exact DTO", () => {
+    expect(
+      decodeSearchRequestQueryV1(
+        url(
+          "?q=gym&before=p50&kinds=user,tool&botId=bot-a&includeArchived=true",
+        ),
+      ),
+    ).toEqual({
+      schemaVersion: 1,
+      query: "gym",
+      before: "p50",
+      kinds: ["user", "tool"],
+      botId: "bot-a",
+      includeArchived: true,
+    });
+  });
+
+  test("refuses an unexpected, repeated, or invalid parameter", () => {
+    expect(() =>
+      decodeSearchRequestQueryV1(url("?q=gym&userId=other")),
+    ).toThrow("not allowed");
+    expect(() => decodeSearchRequestQueryV1(url("?q=gym&q=other"))).toThrow(
+      "repeated",
+    );
+    expect(() =>
+      decodeSearchRequestQueryV1(url("?q=gym&includeArchived=yes")),
+    ).toThrow("includeArchived is invalid");
+    expect(() =>
+      decodeSearchRequestQueryV1(url("?q=gym&kinds=secret")),
+    ).toThrow();
+  });
+});
+
+describe("the search route", () => {
+  test("declines a path it does not own and an unauthenticated request", async () => {
+    const route = createSearchBackendContribution(host());
+    expect(
+      await route.route(
+        new Request("https://frockbot.test/api/bots"),
+        new URL("https://frockbot.test/api/bots"),
+        CONTEXT,
+      ),
+    ).toBeUndefined();
+    expect(
+      await route.route(new Request(url("?q=gym")), url("?q=gym"), {
+        client: "browser",
+      }),
+    ).toBeUndefined();
+  });
+
+  test("answers a grouped page the client decoder accepts", async () => {
+    const route = createSearchBackendContribution(host());
+    const response = await route.route(
+      new Request(url("?q=gym")),
+      url("?q=gym"),
+      CONTEXT,
+    );
+    expect(response?.status).toBe(200);
+    const decoded = decodeClientSearchResultsV1(await response!.json());
+    expect(decoded.groups).toHaveLength(1);
+    expect(decoded.groups[0]).toMatchObject({
+      botId: "bot-a",
+      botName: "Site foreman",
+      archived: false,
+    });
+    expect(decoded.groups[0]!.hits[0]!.deepLink).toBe("/?bot=bot-a#turn-run-1");
+  });
+
+  test("marks a Bot archived from the live lifecycle directory", async () => {
+    const route = createSearchBackendContribution(
+      host({
+        listBotLifecycles: async () => ({
+          schemaVersion: 1,
+          lifecycles: [
+            {
+              schemaVersion: 1,
+              botId: "bot-a",
+              status: "archived",
+              revision: 1,
+            },
+          ],
+        }),
+      }),
+    );
+    const response = await route.route(
+      new Request(url("?q=gym&includeArchived=true")),
+      url("?q=gym&includeArchived=true"),
+      CONTEXT,
+    );
+    const decoded = decodeClientSearchResultsV1(await response!.json());
+    expect(decoded.groups[0]!.archived).toBe(true);
+  });
+
+  test("refuses an invalid query with a definitive 400", async () => {
+    const route = createSearchBackendContribution(host());
+    const response = await route.route(
+      new Request(url("?q=gym&nope=1")),
+      url("?q=gym&nope=1"),
+      CONTEXT,
+    );
+    expect(response?.status).toBe(400);
+    expect(await response!.json()).toMatchObject({
+      code: "invalid-request",
+      definitive: true,
+    });
+  });
+
+  test("rebuilds only on POST", async () => {
+    const route = createSearchBackendContribution(host());
+    const rebuildUrl = new URL("https://frockbot.test/api/search/rebuild");
+    expect(
+      (
+        await route.route(
+          new Request(rebuildUrl, { method: "GET" }),
+          rebuildUrl,
+          CONTEXT,
+        )
+      )?.status,
+    ).toBe(405);
+    const response = await route.route(
+      new Request(rebuildUrl, { method: "POST" }),
+      rebuildUrl,
+      CONTEXT,
+    );
+    expect(
+      decodeClientSearchRebuildReceiptV1(await response!.json()),
+    ).toMatchObject({ status: "rebuilt", indexedRows: 4 });
+  });
+
+  test("defaults to excluding tool rows and archived Bots", async () => {
+    const contribution = host();
+    const route = createSearchBackendContribution(contribution);
+    await route.route(new Request(url("?q=gym")), url("?q=gym"), CONTEXT);
+    expect(contribution.queries[0]).toEqual({ schemaVersion: 1, query: "gym" });
+  });
+});

package/src/backend.ts

@@ -0,0 +1,216 @@
+// The Search Package's gateway Contribution.
+//
+// It sits on the same host as Flock's `/api/bots`, for the same reason: the
+// gateway is where an authenticated `userId` exists, and search is User-scoped
+// by construction — there is no cross-User store to leak from, and the User
+// Durable Object refuses any RPC naming a User it is not.
+//
+// The route owns no state. It decodes the query, asks the User Durable Object,
+// joins the live Bot directory, and answers. Archived Bots are excluded unless
+// asked for, and hidden Bots are returned labelled rather than dropped: the
+// sidebar hides them, which is not the same as them not existing.
+import type { Plugin } from "cordis";
+import type {
+  BotIdentityDirectoryViewV1,
+  BotLifecycleDirectoryViewV1,
+} from "@frockbot/plugin-flock/shared";
+import { groupSearchHitsV1, type SearchBotDescriptorV1 } from "./groups.js";
+import {
+  decodeSearchQueryV1,
+  SearchDecodeError,
+  SEARCH_MAX_CURSOR_LENGTH_V1,
+  SEARCH_MAX_QUERY_LENGTH_V1,
+  type ClientSearchRebuildReceiptV1,
+  type ClientSearchResultsV1,
+  type SearchIndexResultsV1,
+  type SearchQueryV1,
+  type SearchRowKindV1,
+} from "./shared.js";
+
+export interface SearchGatewayHost {
+  searchTranscripts(
+    userId: string,
+    query: SearchQueryV1,
+  ): Promise<SearchIndexResultsV1>;
+  rebuildSearchIndex(userId: string): Promise<ClientSearchRebuildReceiptV1>;
+  listBotIdentities(userId: string): Promise<BotIdentityDirectoryViewV1>;
+  listBotLifecycles(userId: string): Promise<BotLifecycleDirectoryViewV1>;
+}
+
+export interface SearchBackendRouteContribution {
+  packageId: string;
+  route(
+    request: Request,
+    url: URL,
+    context: { userId?: string; client: "browser" | "desktop" },
+  ): Promise<Response | undefined>;
+}
+
+const ALLOWED_PARAMS = new Set([
+  "q",
+  "before",
+  "kinds",
+  "botId",
+  "includeArchived",
+]);
+
+/**
+ * The query string, decoded into the exact DTO.
+ *
+ * URL parameters are the loosest input the Package takes, so they are turned
+ * into the same `SearchQueryV1` every other caller uses and decoded by the
+ * same decoder. An unexpected parameter is a refusal rather than something
+ * quietly ignored, so a client that means something the route does not
+ * implement finds out.
+ */
+export function decodeSearchRequestQueryV1(url: URL): SearchQueryV1 {
+  for (const key of url.searchParams.keys()) {
+    if (!ALLOWED_PARAMS.has(key)) {
+      throw new SearchDecodeError(`search query.${key} is not allowed`);
+    }
+    if (url.searchParams.getAll(key).length > 1) {
+      throw new SearchDecodeError(`search query.${key} is repeated`);
+    }
+  }
+  const query = url.searchParams.get("q") ?? "";
+  if (query.length > SEARCH_MAX_QUERY_LENGTH_V1) {
+    throw new SearchDecodeError("search query.q must be a bounded string");
+  }
+  const before = url.searchParams.get("before");
+  if (before !== null && before.length > SEARCH_MAX_CURSOR_LENGTH_V1) {
+    throw new SearchDecodeError("search query.before must be a bounded string");
+  }
+  const kinds = url.searchParams.get("kinds");
+  const includeArchived = url.searchParams.get("includeArchived");
+  if (
+    includeArchived !== null &&
+    !["true", "false"].includes(includeArchived)
+  ) {
+    throw new SearchDecodeError("search query.includeArchived is invalid");
+  }
+  const botId = url.searchParams.get("botId");
+  return decodeSearchQueryV1({
+    schemaVersion: 1,
+    query,
+    ...(before === null ? {} : { before }),
+    ...(kinds === null
+      ? {}
+      : {
+          kinds: kinds
+            .split(",")
+            .map((kind) => kind.trim())
+            .filter((kind) => kind.length > 0)
+            .filter(
+              (kind, index, all) => all.indexOf(kind) === index,
+            ) as SearchRowKindV1[],
+        }),
+    ...(botId === null ? {} : { botId }),
+    ...(includeArchived === null
+      ? {}
+      : { includeArchived: includeArchived === "true" }),
+  });
+}
+
+function errorResponse(error: unknown): Response {
+  if (
+    error instanceof SearchDecodeError ||
+    (typeof error === "object" &&
+      error !== null &&
+      "name" in error &&
+      error.name === "SearchDecodeError")
+  ) {
+    return Response.json(
+      {
+        error:
+          error instanceof Error ? error.message : "search request is invalid",
+        code: "invalid-request",
+        definitive: true,
+      },
+      { status: 400 },
+    );
+  }
+  return Response.json(
+    { error: error instanceof Error ? error.message : "search failed" },
+    { status: 500 },
+  );
+}
+
+/** The live directory a query is grouped and filtered against. */
+async function readDirectory(
+  host: SearchGatewayHost,
+  userId: string,
+): Promise<SearchBotDescriptorV1[]> {
+  const [identities, lifecycles] = await Promise.all([
+    host.listBotIdentities(userId),
+    host.listBotLifecycles(userId),
+  ]);
+  const status = new Map(
+    lifecycles.lifecycles.map((lifecycle) => [
+      lifecycle.botId,
+      lifecycle.status,
+    ]),
+  );
+  return identities.identities.map((identity) => ({
+    botId: identity.botId,
+    name: identity.name,
+    archived: status.get(identity.botId) === "archived",
+    hidden: identity.hiddenFromSidebar,
+  }));
+}
+
+export function createSearchBackendContribution(
+  host: SearchGatewayHost,
+): SearchBackendRouteContribution {
+  return {
+    packageId: "search",
+    async route(request, url, context) {
+      if (!context.userId) return undefined;
+      const isSearch = url.pathname === "/api/search";
+      const isRebuild = url.pathname === "/api/search/rebuild";
+      if (!isSearch && !isRebuild) return undefined;
+      const userId = context.userId;
+      try {
+        if (isRebuild) {
+          if (request.method !== "POST") {
+            return Response.json(
+              { error: "method not allowed" },
+              { status: 405 },
+            );
+          }
+          return Response.json(await host.rebuildSearchIndex(userId));
+        }
+        if (request.method !== "GET") {
+          return Response.json(
+            { error: "method not allowed" },
+            { status: 405 },
+          );
+        }
+        const query = decodeSearchRequestQueryV1(url);
+        const [results, directory] = await Promise.all([
+          host.searchTranscripts(userId, query),
+          readDirectory(host, userId),
+        ]);
+        // Archiving is already applied inside the index, against this same
+        // live directory, so this route filters nothing: it only names the
+        // Bots the hits belong to. One filter, in the place that owns the
+        // rows, is the only way the two can never disagree.
+        const grouped: ClientSearchResultsV1 = groupSearchHitsV1(
+          results,
+          directory,
+        );
+        return Response.json(grouped);
+      } catch (error) {
+        return errorResponse(error);
+      }
+    },
+  };
+}
+
+export namespace createSearchBackendContribution {
+  export function plugin(
+    host: SearchGatewayHost,
+    lifecycle: { mount(value: SearchBackendRouteContribution): () => void },
+  ): Plugin {
+    return () => lifecycle.mount(createSearchBackendContribution(host));
+  }
+}

package/src/bot.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from "bun:test";
+import {
+  isSettledSearchRunV1,
+  searchRowsFromClientRunV1,
+  type SearchProjectableRunV1,
+} from "./bot.ts";
+
+function run(
+  overrides: Partial<SearchProjectableRunV1> = {},
+): SearchProjectableRunV1 {
+  return {
+    runId: "run-1",
+    admittedAt: "2026-08-31T00:00:00.000Z",
+    input: "How is the gym build going?",
+    status: "completed",
+    events: [],
+    responseText: "Framing is done.",
+    ...overrides,
+  };
+}
+
+describe("the settled-run projection", () => {
+  test("projects the user input and the assistant answer", () => {
+    expect(searchRowsFromClientRunV1("bot-a", run())).toEqual([
+      {
+        botId: "bot-a",
+        runId: "run-1",
+        seq: 0,
+        kind: "user",
+        at: "2026-08-31T00:00:00.000Z",
+        body: "How is the gym build going?",
+      },
+      {
+        botId: "bot-a",
+        runId: "run-1",
+        seq: 1,
+        kind: "assistant",
+        at: "2026-08-31T00:00:00.000Z",
+        body: "Framing is done.",
+      },
+    ]);
+  });
+
+  test("projects a tool call with its result as one `tool` row", () => {
+    const rows = searchRowsFromClientRunV1(
+      "bot-a",
+      run({
+        events: [
+          { type: "tool/call", call: { id: "tool-1", name: "shell" } },
+          { type: "tool/result", callId: "tool-1", content: "ok" },
+        ],
+      }),
+    );
+    expect(rows.map((entry) => entry.kind)).toEqual([
+      "user",
+      "tool",
+      "assistant",
+    ]);
+    expect(rows[1]!.body).toBe("shell\nok");
+  });
+
+  test("projects nothing for a run that has not settled", () => {
+    expect(isSettledSearchRunV1({ status: "running" })).toBe(false);
+    expect(
+      searchRowsFromClientRunV1("bot-a", run({ status: "running" })),
+    ).toEqual([]);
+  });
+
+  test("a failed run still contributes its user input", () => {
+    const rows = searchRowsFromClientRunV1(
+      "bot-a",
+      run({
+        status: "failed",
+        responseText: undefined,
+      }),
+    );
+    expect(rows.map((entry) => entry.kind)).toEqual(["user"]);
+  });
+
+  test("is deterministic, so a rebuild reproduces the settlement-time rows", () => {
+    const settled = run({
+      events: [
+        { type: "tool/call", call: { id: "tool-1", name: "shell" } },
+        { type: "tool/result", callId: "tool-1", content: "ok" },
+      ],
+    });
+    expect(searchRowsFromClientRunV1("bot-a", settled)).toEqual(
+      searchRowsFromClientRunV1("bot-a", settled),
+    );
+  });
+
+  test("drops empty bodies without leaving a gap in `seq`", () => {
+    const rows = searchRowsFromClientRunV1(
+      "bot-a",
+      run({ responseText: "   " }),
+    );
+    expect(rows.map((entry) => entry.seq)).toEqual([0]);
+  });
+
+  test("projects nothing for a run with no admission time to order it by", () => {
+    expect(
+      searchRowsFromClientRunV1("bot-a", run({ admittedAt: undefined })),
+    ).toEqual([]);
+  });
+});