@stigmer/server 3.14.0-dev.20260910084630

package/src/query/activity/handler.ts

@@ -0,0 +1,341 @@
+/**
+ * Recent-activity handler — ports pkg/query/activity/handler/handler.go:
+ * sessions and workflow executions merged into one time-sorted list for
+ * the console's Recents sidebar.
+ *
+ * This is the OSS twin of the cloud's ListRecentActivityHandler; the
+ * merge, ordering, projection, and filtering semantics are deliberately
+ * identical (stigmer#461). What differs is only what single-tenancy
+ * removes: with NO ListReadScope composed there is no id enumeration
+ * (the candidate set is every stored row) and the request's org is a
+ * no-op (a recents filter stricter than the per-kind lists it summarizes
+ * would hide locally-owned rows); load-all-then-sort-in-memory replaces
+ * per-kind SQL LIMIT windows (each kind's newest page_size rows are a
+ * superset of its contribution to the merged page — the identical final
+ * list; the full scan is this store's contract, the same pattern every
+ * OSS list handler uses). With a composed ListReadScope (20260830.01,
+ * census lane 22) both loads narrow to the caller's authorized ids ∩
+ * the request's org when non-blank — the Java handler's two
+ * listAuthorizedResourceIds calls and its findRecentByIdsAndOrg org arm.
+ *
+ * Proven by __tests__/handler.test.ts (Go's handler_test.go arms) and
+ * activity.conformance.test.ts on local.
+ */
+import { create, fromBinary } from "@bufbuild/protobuf";
+import { TimestampSchema } from "@bufbuild/protobuf/wkt";
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+
+import {
+  ListRecentActivityResponseSchema,
+  RecentActivityEntrySchema,
+} from "@stigmer/protos/ai/stigmer/activity/v1/io_pb";
+import type {
+  ListRecentActivityRequest,
+  ListRecentActivityResponse,
+  RecentActivityEntry,
+} from "@stigmer/protos/ai/stigmer/activity/v1/io_pb";
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceAudit } from "@stigmer/protos/ai/stigmer/commons/apiresource/status_pb";
+import type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+
+import type { Logger } from "../../boot/logger.js";
+import type { CallerIdentity } from "../../extensions/identity.js";
+import type { ListReadScope } from "../../extensions/list-read-scope.js";
+import type { Store } from "../../store/interface.js";
+
+/**
+ * defaultPageSize / maxPageSize mirror the cloud handler's
+ * DEFAULT_PAGE_SIZE / MAX_PAGE_SIZE — the page contract is part of the
+ * cross-edition behavior, not an implementation detail.
+ */
+export const DEFAULT_PAGE_SIZE = 30;
+export const MAX_PAGE_SIZE = 100;
+
+/**
+ * The platform-wide sentinel subject stamped on sessions created without
+ * a user-provided title (the SDK's PENDING_SUBJECT, the CLI's resume
+ * flow, the runner's call-agent, and this server's agent-execution create
+ * all use the same literal). The sidebar shows the friendlier placeholder
+ * until subject generation replaces the sentinel.
+ */
+export const AUTO_CREATED_SESSION_SUBJECT = "Auto-created session";
+
+export const UNTITLED_SESSION_SUBJECT = "Untitled session";
+export const UNTITLED_EXECUTION_SUBJECT = "Untitled execution";
+
+/**
+ * Marks a session as runtime-originated. Recents shows personal sessions
+ * only (cloud design decision 012): channel conversations, guest/share
+ * sessions, and schedule-triggered sessions are excluded for every caller
+ * — each runtime surface owns its own list. Keys match the cloud's
+ * RUNTIME_ORIGIN_LABELS exactly; share/guest are cloud-only today but
+ * excluded identically so a future OSS share surface cannot silently
+ * regress the recents policy.
+ */
+export const RUNTIME_ORIGIN_LABELS: readonly string[] = [
+  "stigmer.ai/channel-id",
+  "stigmer.ai/share-id",
+  "stigmer.ai/guest-cookie-id",
+  "stigmer.ai/schedule-id",
+];
+
+/** Answers ActivityQueryController.listRecentActivity against the store. */
+export class ActivityHandler {
+  constructor(
+    private readonly store: Store,
+    private readonly logger: Logger,
+    private readonly listReadScope: ListReadScope | undefined,
+  ) {}
+
+  /**
+   * Go ListRecentActivity: load both kinds, project to sidebar entries,
+   * merge-sort newest-first, trim to the page. With a composed scope the
+   * per-kind loads narrow to the caller's authorized ids ∩ the request's
+   * org (blank = permission-bounded across orgs, the repo convention).
+   */
+  async listRecentActivity(
+    request: ListRecentActivityRequest,
+    identity: CallerIdentity,
+  ): Promise<ListRecentActivityResponse> {
+    const pageSize = normalizePageSize(request.pageSize);
+
+    let sessionScope: ReadonlySet<string> | undefined;
+    let executionScope: ReadonlySet<string> | undefined;
+    if (this.listReadScope !== undefined) {
+      sessionScope = await this.listReadScope.authorizedResourceIds(
+        identity,
+        ApiResourceKind.session,
+      );
+      executionScope = await this.listReadScope.authorizedResourceIds(
+        identity,
+        ApiResourceKind.workflow_execution,
+      );
+    }
+
+    const sessions = await this.loadSessions(sessionScope, request.org);
+    const executions = await this.loadExecutions(executionScope, request.org);
+
+    // Sessions before executions, then a stable sort: entries with equal
+    // timestamps keep this insertion order — the same tie-break the
+    // cloud gets from java.util.List.sort's stability over the same load
+    // order (JS Array.prototype.sort is stable, matching Go's
+    // sort.SliceStable).
+    let entries = [...sessions, ...executions].sort((a, b) => {
+      if (timestampAfter(a.updatedAt, b.updatedAt)) {
+        return -1;
+      }
+      if (timestampAfter(b.updatedAt, a.updatedAt)) {
+        return 1;
+      }
+      return 0;
+    });
+
+    if (entries.length > pageSize) {
+      entries = entries.slice(0, pageSize);
+    }
+
+    this.logger.debug("Recent activity merged", {
+      entries: entries.length,
+      page_size: pageSize,
+    });
+
+    return create(ListRecentActivityResponseSchema, { entries });
+  }
+
+  /**
+   * Go loadSessions: every stored personal session projected to a recents
+   * entry; runtime-originated sessions excluded.
+   */
+  private async loadSessions(
+    authorizedIds: ReadonlySet<string> | undefined,
+    org: string,
+  ): Promise<RecentActivityEntry[]> {
+    const rows = await this.store.listResources(ApiResourceKind.session);
+    const entries: RecentActivityEntry[] = [];
+    for (const row of rows) {
+      let session;
+      try {
+        session = fromBinary(SessionSchema, row);
+      } catch {
+        this.logger.warn("Skipping undecodable session row in recent activity");
+        continue;
+      }
+      if (hasRuntimeOriginLabel(session.metadata)) {
+        continue;
+      }
+      if (
+        authorizedIds !== undefined &&
+        !isVisibleUnderScope(authorizedIds, org, session.metadata)
+      ) {
+        continue;
+      }
+      entries.push(
+        create(RecentActivityEntrySchema, {
+          id: session.metadata?.id ?? "",
+          type: "session",
+          subject: resolveSubject(session.spec?.subject ?? ""),
+          updatedAt: extractUpdatedAt(session.status?.audit),
+        }),
+      );
+    }
+    return entries;
+  }
+
+  /** Go loadExecutions: every stored workflow execution projected. */
+  private async loadExecutions(
+    authorizedIds: ReadonlySet<string> | undefined,
+    org: string,
+  ): Promise<RecentActivityEntry[]> {
+    const rows = await this.store.listResources(
+      ApiResourceKind.workflow_execution,
+    );
+    const entries: RecentActivityEntry[] = [];
+    for (const row of rows) {
+      let execution;
+      try {
+        execution = fromBinary(WorkflowExecutionSchema, row);
+      } catch {
+        this.logger.warn(
+          "Skipping undecodable workflow execution row in recent activity",
+        );
+        continue;
+      }
+      if (
+        authorizedIds !== undefined &&
+        !isVisibleUnderScope(authorizedIds, org, execution.metadata)
+      ) {
+        continue;
+      }
+      const name = execution.metadata?.name ?? "";
+      entries.push(
+        create(RecentActivityEntrySchema, {
+          id: execution.metadata?.id ?? "",
+          type: "workflow_execution",
+          subject: name === "" ? UNTITLED_EXECUTION_SUBJECT : name,
+          updatedAt: extractUpdatedAt(execution.status?.audit),
+          status: resolvePhase(
+            execution.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED,
+          ),
+        }),
+      );
+    }
+    return entries;
+  }
+}
+
+/**
+ * The scoped-visibility test both loads share when a scope is composed:
+ * the row's id must be authorized and, when the request names an org, the
+ * row must belong to it (the Java findRecentByIdsAndOrg arm).
+ */
+function isVisibleUnderScope(
+  authorizedIds: ReadonlySet<string>,
+  org: string,
+  metadata: ApiResourceMetadata | undefined,
+): boolean {
+  if (!authorizedIds.has(metadata?.id ?? "")) {
+    return false;
+  }
+  return org === "" || (metadata?.org ?? "") === org;
+}
+
+/** Go normalizePageSize: ≤0 → default 30; >100 → cap 100. */
+export function normalizePageSize(requested: number): number {
+  if (requested <= 0) {
+    return DEFAULT_PAGE_SIZE;
+  }
+  if (requested > MAX_PAGE_SIZE) {
+    return MAX_PAGE_SIZE;
+  }
+  return requested;
+}
+
+function hasRuntimeOriginLabel(
+  metadata: ApiResourceMetadata | undefined,
+): boolean {
+  const labels = metadata?.labels;
+  if (labels === undefined) {
+    return false;
+  }
+  // Object.hasOwn, not `in`: own keys only, matching Go's map lookup
+  // (the #17 least-privilege-filter precedent).
+  return RUNTIME_ORIGIN_LABELS.some((key) => Object.hasOwn(labels, key));
+}
+
+/**
+ * Go resolveSubject: missing subjects AND the auto-created sentinel map
+ * to the display placeholder — a just-created session shows "Untitled
+ * session" until subject generation writes a real title.
+ */
+export function resolveSubject(subject: string): string {
+  if (subject === "" || subject === AUTO_CREATED_SESSION_SUBJECT) {
+    return UNTITLED_SESSION_SUBJECT;
+  }
+  return subject;
+}
+
+/**
+ * Go resolvePhase: the lifecycle phase → the display token the console's
+ * status badge renders. Unspecified (and any future value this build
+ * does not know) reads as "unknown" — no badge.
+ */
+export function resolvePhase(phase: ExecutionPhase): string {
+  switch (phase) {
+    case ExecutionPhase.EXECUTION_PENDING:
+      return "pending";
+    case ExecutionPhase.EXECUTION_IN_PROGRESS:
+      return "running";
+    case ExecutionPhase.EXECUTION_COMPLETED:
+      return "completed";
+    case ExecutionPhase.EXECUTION_FAILED:
+      return "failed";
+    case ExecutionPhase.EXECUTION_CANCELLED:
+      return "cancelled";
+    case ExecutionPhase.EXECUTION_TERMINATED:
+      return "terminated";
+    case ExecutionPhase.EXECUTION_PAUSED:
+      return "paused";
+    default:
+      return "unknown";
+  }
+}
+
+/**
+ * Go extractUpdatedAt — the entry's sort key: statusAudit.updatedAt
+ * (bumped on meaningful status changes; heartbeats deliberately do NOT
+ * bump it) falling back to specAudit.createdAt for rows whose status
+ * audit was never stamped (older builds or external tooling; OSS creates
+ * always stamp both slots).
+ */
+export function extractUpdatedAt(
+  audit: ApiResourceAudit | undefined,
+): Timestamp {
+  const updatedAt = audit?.statusAudit?.updatedAt;
+  if (updatedAt !== undefined) {
+    return updatedAt;
+  }
+  const createdAt = audit?.specAudit?.createdAt;
+  if (createdAt !== undefined) {
+    return createdAt;
+  }
+  return create(TimestampSchema);
+}
+
+/**
+ * Go timestampAfter: a sorts strictly after b (newer first), comparing
+ * (seconds, nanos) exactly like the cloud's comparator.
+ */
+export function timestampAfter(
+  a: Timestamp | undefined,
+  b: Timestamp | undefined,
+): boolean {
+  const aSeconds = a?.seconds ?? 0n;
+  const bSeconds = b?.seconds ?? 0n;
+  if (aSeconds !== bSeconds) {
+    return aSeconds > bSeconds;
+  }
+  return (a?.nanos ?? 0) > (b?.nanos ?? 0);
+}

package/src/query/search/__tests__/controller.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Pins the controllers' error mapping (Go search_controller.go
+ * toGRPCError + activity_controller.go): the string-contains
+ * InvalidArgument arms CARRY the wrapped handler text, everything else
+ * sanitizes to the static Internal copy (#478) — including the
+ * deliberately-quirky Go arm where a store error containing "invalid"
+ * answers InvalidArgument with its raw text. Driven through
+ * createRouterTransport so the mapping is proven at the ConnectRPC
+ * boundary, not by calling private functions.
+ */
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError, createClient } from "@connectrpc/connect";
+import { createRouterTransport } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { ListRecentActivityRequestSchema } from "@stigmer/protos/ai/stigmer/activity/v1/io_pb";
+import { ActivityQueryController } from "@stigmer/protos/ai/stigmer/activity/v1/query_pb";
+import { SearchRequestSchema } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import { SearchService } from "@stigmer/protos/ai/stigmer/search/v1/query_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { createVerifierChainInterceptor } from "../../../pipeline/interceptors/auth.js";
+import {
+  tempStore,
+  type TempStore,
+} from "../../../store/sqlite/__tests__/support.js";
+import { ActivityHandler } from "../../activity/handler.js";
+import { registerActivityServices } from "../../activity/controller.js";
+import { registerSearchServices } from "../controller.js";
+import { SearchHandler } from "../handler.js";
+import type { SearchQueryStore } from "../query-store.js";
+import { emptyResult } from "../paged-result.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => undefined,
+});
+
+function searchClientOver(store: SearchQueryStore) {
+  // The zero-verifier chain stamps the trusted-local identity — the
+  // controller reads it for the (scope-less here) list-read seam.
+  const transport = createRouterTransport(
+    (router) => {
+      registerSearchServices(router, {
+        handler: new SearchHandler(store, silentLogger, undefined),
+        logger: silentLogger,
+      });
+    },
+    {
+      router: {
+        interceptors: [createVerifierChainInterceptor([], [], silentLogger)],
+      },
+    },
+  );
+  return createClient(SearchService, transport);
+}
+
+async function grpcError(promise: Promise<unknown>): Promise<ConnectError> {
+  try {
+    await promise;
+  } catch (error) {
+    return ConnectError.from(error);
+  }
+  throw new Error("expected the call to reject");
+}
+
+describe("search error mapping (Go toGRPCError)", () => {
+  it("sanitizes an unmatched store failure to Internal 'search failed' (#478)", async () => {
+    const client = searchClientOver({
+      search: () => Promise.reject(new Error("disk exploded at /var/lib")),
+      rebuildIndex: () => Promise.resolve(0),
+    });
+    const error = await grpcError(
+      client.search(create(SearchRequestSchema, { query: "x" })),
+    );
+    expect(error.code).toBe(Code.Internal);
+    // The raw text stays off the wire — only the static copy crosses.
+    expect(error.rawMessage).toBe("search failed");
+  });
+
+  it("maps a store error containing 'invalid' to InvalidArgument WITH the wrapped text (Go's string-contains quirk)", async () => {
+    const client = searchClientOver({
+      search: () => Promise.reject(new Error("invalid cursor state")),
+      rebuildIndex: () => Promise.resolve(0),
+    });
+    const error = await grpcError(
+      client.search(create(SearchRequestSchema, { query: "x" })),
+    );
+    expect(error.code).toBe(Code.InvalidArgument);
+    expect(error.rawMessage).toBe("search failed: invalid cursor state");
+  });
+
+  it("answers the handler's defensive protovalidate arm as InvalidArgument", async () => {
+    // Only the identity interceptor rides this transport (no
+    // protovalidate), so the HANDLER's own validate — Go's step 1,
+    // wire-unreachable behind the real chain — answers. The wrapped
+    // "validation failed: ..." text string-matches to InvalidArgument.
+    const client = searchClientOver({
+      search: () => Promise.resolve(emptyResult()),
+      rebuildIndex: () => Promise.resolve(0),
+    });
+    const error = await grpcError(
+      client.search(create(SearchRequestSchema, { query: "x".repeat(501) })),
+    );
+    expect(error.code).toBe(Code.InvalidArgument);
+    expect(error.rawMessage).toContain("validation failed");
+  });
+});
+
+describe("activity error mapping", () => {
+  it("sanitizes a storage failure to Internal 'failed to list recent activity' (#478)", async () => {
+    // A CLOSED store's reads throw — the handler's only failure mode,
+    // reached without stubbing the wide Store interface.
+    const temp: TempStore = tempStore();
+    try {
+      await temp.store.close();
+
+      const transport = createRouterTransport(
+        (router) => {
+          registerActivityServices(router, {
+            handler: new ActivityHandler(temp.store, silentLogger, undefined),
+            logger: silentLogger,
+          });
+        },
+        {
+          router: {
+            interceptors: [
+              createVerifierChainInterceptor([], [], silentLogger),
+            ],
+          },
+        },
+      );
+      const client = createClient(ActivityQueryController, transport);
+
+      const error = await grpcError(
+        client.listRecentActivity(
+          create(ListRecentActivityRequestSchema, { pageSize: 10 }),
+        ),
+      );
+      expect(error.code).toBe(Code.Internal);
+      expect(error.rawMessage).toBe("failed to list recent activity");
+    } finally {
+      await temp.cleanup();
+    }
+  });
+});

package/src/query/search/__tests__/criteria.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Pins SearchCriteria against Go's search_criteria_test.go tables:
+ * normalization (trimming, clamps), the 500-char boundary, the three-mode
+ * contract, and the #440 arm — named-but-unsearchable kinds yield an EMPTY
+ * effective set, never a discover fallback. The kind_meta derivation is
+ * pinned here too: 13 searchable kinds, project included (DD-D).
+ */
+import { describe, expect, it } from "vitest";
+
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  DEFAULT_PAGE_SIZE,
+  MAX_PAGE_SIZE,
+  MAX_QUERY_LENGTH,
+  SearchCriteria,
+  searchIndexedKinds,
+} from "../criteria.js";
+
+function criteria(overrides?: {
+  kinds?: ApiResourceKind[];
+  query?: string;
+  org?: string;
+  excludePublic?: boolean;
+  crossOrgPublic?: boolean;
+  pageNumber?: number;
+  pageSize?: number;
+}): SearchCriteria {
+  return SearchCriteria.create(
+    overrides?.kinds ?? [],
+    overrides?.query ?? "",
+    overrides?.org ?? "",
+    overrides?.excludePublic ?? false,
+    overrides?.crossOrgPublic ?? false,
+    overrides?.pageNumber ?? 1,
+    overrides?.pageSize ?? 20,
+  );
+}
+
+describe("searchIndexedKinds derivation (kind_meta)", () => {
+  it("derives exactly the 13 searchable kinds, project included", () => {
+    // Go's SearchableKinds map, pinned by its invariant test against the
+    // same kind_meta derivation. project rides #14 (DD-D) although its
+    // domain ports with #16 — RebuildIndex on an adopted Go database
+    // must be able to re-index existing project rows.
+    expect([...searchIndexedKinds()].sort((a, b) => a - b)).toEqual(
+      [
+        ApiResourceKind.agent,
+        ApiResourceKind.skill,
+        ApiResourceKind.mcp_server,
+        ApiResourceKind.workflow,
+        ApiResourceKind.project,
+        ApiResourceKind.environment,
+        ApiResourceKind.session,
+        ApiResourceKind.agent_execution,
+        ApiResourceKind.agent_instance,
+        ApiResourceKind.execution_context,
+        ApiResourceKind.organization,
+        ApiResourceKind.workflow_execution,
+        ApiResourceKind.workflow_instance,
+      ].sort((a, b) => a - b),
+    );
+  });
+
+  it("excludes not_search_indexed kinds (agent_channel, memory)", () => {
+    const kinds = searchIndexedKinds();
+    expect(kinds).not.toContain(ApiResourceKind.agent_channel);
+    expect(kinds).not.toContain(ApiResourceKind.channel_app);
+    expect(kinds).not.toContain(ApiResourceKind.memory);
+  });
+});
+
+describe("SearchCriteria normalization (Go NewSearchCriteria)", () => {
+  it("keeps valid input verbatim", () => {
+    const c = criteria({
+      kinds: [ApiResourceKind.agent, ApiResourceKind.skill],
+      query: "kubernetes",
+      org: "acme",
+      pageNumber: 2,
+      pageSize: 50,
+    });
+    expect(c.kinds()).toEqual([ApiResourceKind.agent, ApiResourceKind.skill]);
+    expect(c.query()).toBe("kubernetes");
+    expect(c.orgFilter()).toBe("acme");
+    expect(c.pageNumber()).toBe(2);
+    expect(c.pageSize()).toBe(50);
+  });
+
+  it("trims the query and the org filter", () => {
+    const c = criteria({ query: "  hello  ", org: "  acme  " });
+    expect(c.query()).toBe("hello");
+    expect(c.orgFilter()).toBe("acme");
+  });
+
+  it("rejects a query over the cap with Go's exact message", () => {
+    expect(() =>
+      criteria({ query: "x".repeat(MAX_QUERY_LENGTH + 1) }),
+    ).toThrowError(
+      "search query exceeds maximum length of 500 characters",
+    );
+  });
+
+  it("accepts a query at exactly the cap", () => {
+    const c = criteria({ query: "x".repeat(MAX_QUERY_LENGTH) });
+    expect(c.query().length).toBe(MAX_QUERY_LENGTH);
+  });
+
+  it("clamps the page number: 0 and negatives normalize to 1", () => {
+    expect(criteria({ pageNumber: 0 }).pageNumber()).toBe(1);
+    expect(criteria({ pageNumber: -5 }).pageNumber()).toBe(1);
+    expect(criteria({ pageNumber: 3 }).pageNumber()).toBe(3);
+  });
+
+  it("clamps the page size: <1 → default, >100 → max", () => {
+    expect(criteria({ pageSize: 0 }).pageSize()).toBe(DEFAULT_PAGE_SIZE);
+    expect(criteria({ pageSize: -1 }).pageSize()).toBe(DEFAULT_PAGE_SIZE);
+    expect(criteria({ pageSize: 1000 }).pageSize()).toBe(MAX_PAGE_SIZE);
+    expect(criteria({ pageSize: MAX_PAGE_SIZE }).pageSize()).toBe(
+      MAX_PAGE_SIZE,
+    );
+  });
+});
+
+describe("mode selection", () => {
+  it("empty kinds is discover mode; requested kinds is not", () => {
+    expect(criteria({ kinds: [] }).isDiscoverMode()).toBe(true);
+    expect(
+      criteria({ kinds: [ApiResourceKind.agent] }).isDiscoverMode(),
+    ).toBe(false);
+  });
+
+  it("hasQuery: empty and whitespace-only queries mean list mode", () => {
+    expect(criteria({ query: "" }).hasQuery()).toBe(false);
+    expect(criteria({ query: "   " }).hasQuery()).toBe(false);
+    expect(criteria({ query: "x" }).hasQuery()).toBe(true);
+  });
+
+  it("hasOrgFilter follows the trimmed org", () => {
+    expect(criteria({ org: "" }).hasOrgFilter()).toBe(false);
+    expect(criteria({ org: "acme" }).hasOrgFilter()).toBe(true);
+  });
+});
+
+describe("effectiveKinds (the #440 contract)", () => {
+  it("discover mode returns every searchable kind", () => {
+    expect(criteria({ kinds: [] }).effectiveKinds()).toEqual(
+      searchIndexedKinds(),
+    );
+  });
+
+  it("specific kinds pass through when searchable", () => {
+    expect(
+      criteria({
+        kinds: [ApiResourceKind.agent, ApiResourceKind.workflow],
+      }).effectiveKinds(),
+    ).toEqual([ApiResourceKind.agent, ApiResourceKind.workflow]);
+  });
+
+  it("non-searchable kinds are silently dropped from a mixed request", () => {
+    expect(
+      criteria({
+        kinds: [ApiResourceKind.agent, ApiResourceKind.agent_channel],
+      }).effectiveKinds(),
+    ).toEqual([ApiResourceKind.agent]);
+  });
+
+  it("ONLY non-searchable kinds yields the empty set — never discover (#440)", () => {
+    const c = criteria({ kinds: [ApiResourceKind.agent_channel] });
+    expect(c.effectiveKinds()).toEqual([]);
+    expect(c.isDiscoverMode()).toBe(false);
+  });
+
+  it("kinds() returns the request verbatim, including unsearchable ones", () => {
+    const c = criteria({ kinds: [ApiResourceKind.agent_channel] });
+    expect(c.kinds()).toEqual([ApiResourceKind.agent_channel]);
+  });
+});
+
+describe("offset", () => {
+  it("computes the zero-indexed row offset (Go Offset)", () => {
+    expect(criteria({ pageNumber: 1, pageSize: 20 }).offset()).toBe(0);
+    expect(criteria({ pageNumber: 2, pageSize: 20 }).offset()).toBe(20);
+    expect(criteria({ pageNumber: 3, pageSize: 50 }).offset()).toBe(100);
+  });
+});