@opengeni/api-router 2.4.2-canary.0 → 2.5.0

package/dist/{chunk-L7GVVSSQ.js → chunk-QESX7HDK.js}

@@ -2164,6 +2164,14 @@ import {
   TASK_NOTE_MAX_LIFETIME_DAYS,
   TASK_NOTE_REASON_MAX_BYTES,
   TASK_NOTE_TEXT_MAX_BYTES,
+  WORK_CLAIM_CANONICAL_KEY_MAX_BYTES,
+  WORK_CLAIM_DISPLAY_LABEL_MAX_BYTES,
+  WORK_CLAIM_DISCOVERY_LIMIT,
+  WORK_CLAIM_NAMESPACE_MAX_BYTES,
+  WORK_CLAIM_VERSION_VALUE_MAX_BYTES,
+  WORK_DISCOVERY_QUERY_MAX_CHARS,
+  WORK_DISCOVERY_RECENT_HOURS_MAX,
+  WorkClaimSubjectType,
   SubmitHumanInputResponseRequest
 } from "@opengeni/contracts";
 import {
@@ -2221,6 +2229,8 @@ import {
   createTaskNote,
   listTaskNotes,
   replaceTaskNote,
+  releaseWorkClaim,
+  upsertWorkClaim,
   acceptSessionHumanInputResponse,
   HumanInputResponseValidationError
 } from "@opengeni/db";
@@ -18354,6 +18364,89 @@ async function deleteScheduledTaskWithDurableCleanup(deps, input) {
   return { task: result.task, changed: result.changed };
 }
 
+// src/work-discovery-observability.ts
+var RESULT_BUCKETS = [0, 1, 2, 4, 8, 16, 32, 64, 100];
+var RESPONSE_BYTE_BUCKETS = [512, 1024, 4096, 16384, 65536, 128e3, 262144];
+var DURATION_BUCKETS = [5e-3, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5];
+function summarizeWorkDiscoveryRows(rows) {
+  const matchCounts = {};
+  let overlapCount = 0;
+  for (const row of rows) {
+    if (row.relatedWork.possibleOverlap) overlapCount += 1;
+    const matchClass = row.relatedWork.match?.class;
+    if (matchClass) matchCounts[matchClass] = (matchCounts[matchClass] ?? 0) + 1;
+  }
+  return { resultCount: rows.length, overlapCount, matchCounts };
+}
+function observeWorkDiscovery(observability, observation) {
+  if (!observability) return;
+  const labels = {
+    surface: observation.surface,
+    mode: observation.mode,
+    outcome: observation.outcome,
+    authorization_scope: observation.authorizationScope
+  };
+  try {
+    observability.incrementCounter({
+      name: "opengeni_work_discovery_requests_total",
+      help: "Advisory work-discovery requests by bounded surface, mode, outcome, and authorization scope.",
+      labels
+    });
+    observability.observeHistogram({
+      name: "opengeni_work_discovery_duration_seconds",
+      help: "Advisory work-discovery request duration in seconds.",
+      labels,
+      buckets: DURATION_BUCKETS,
+      value: Math.max(0, observation.durationMs) / 1e3
+    });
+    observability.observeHistogram({
+      name: "opengeni_work_discovery_results",
+      help: "Bounded advisory work-discovery result rows per request.",
+      labels: { surface: observation.surface, mode: observation.mode },
+      buckets: RESULT_BUCKETS,
+      value: Math.max(0, Math.floor(observation.resultCount))
+    });
+    observability.observeHistogram({
+      name: "opengeni_work_discovery_response_bytes",
+      help: "Serialized advisory work-discovery response bytes.",
+      labels: { surface: observation.surface, mode: observation.mode },
+      buckets: RESPONSE_BYTE_BUCKETS,
+      value: Math.max(0, Math.floor(observation.responseBytes))
+    });
+    if (observation.overlapCount > 0) {
+      observability.incrementCounter({
+        name: "opengeni_work_discovery_overlap_results_total",
+        help: "Advisory discovery rows carrying a possible-overlap explanation.",
+        labels: { surface: observation.surface, mode: observation.mode },
+        amount: Math.floor(observation.overlapCount)
+      });
+    }
+    for (const matchClass of ["exact_subject", "title", "goal", "fuzzy"]) {
+      const amount = Math.floor(observation.matchCounts[matchClass] ?? 0);
+      if (amount < 1) continue;
+      observability.incrementCounter({
+        name: "opengeni_work_discovery_matches_total",
+        help: "Advisory discovery matches by stable explanation class.",
+        labels: {
+          surface: observation.surface,
+          mode: observation.mode,
+          match_class: matchClass
+        },
+        amount
+      });
+    }
+  } catch {
+    try {
+      observability.incrementCounter({
+        name: "opengeni_observability_observer_errors_total",
+        help: "Observability observer failures isolated from product execution.",
+        labels: { observer: "work_discovery" }
+      });
+    } catch {
+    }
+  }
+}
+
 // src/mcp/server.ts
 var ORCHESTRATION_FAILURE_CODE_MAX_LENGTH = 128;
 var ORCHESTRATION_FAILURE_MESSAGE_MAX_UTF8_BYTES = 1024;
@@ -18455,6 +18548,8 @@ var FIRST_PARTY_TOOL_AUTHORIZATION = {
   task_note_save: { sessionRequired: true, allOf: ["sessions:control"] },
   task_note_archive: { sessionRequired: true, allOf: ["sessions:control"] },
   task_note_replace: { sessionRequired: true, allOf: ["sessions:control"] },
+  work_claim_upsert: { sessionRequired: true, allOf: ["sessions:control"] },
+  work_claim_release: { sessionRequired: true, allOf: ["sessions:control"] },
   knowledge_propose: { sessionRequired: true, allOf: ["documents:search"] },
   knowledge_correct: { sessionRequired: true, allOf: ["documents:search"] },
   task_note_promote_knowledge: {
@@ -18784,6 +18879,9 @@ function buildOpenGeniMcpServer(deps, grant, options = {}) {
   if (sessionId !== null && exactAgentAttemptClaims(grant) !== null) {
     registerPreferenceRegistryTools(server, deps, grant, json);
     registerTaskNoteTools(server, deps, grant, sessionId, json);
+    if (deps.settings.workClaimMutationsEnabled) {
+      registerWorkClaimTools(server, deps, grant, sessionId, json);
+    }
     const attempt = exactAgentAttemptClaims(grant);
     registerCompanyBrainGovernedWriteTools({
       server,
@@ -20865,6 +20963,118 @@ function registerTaskNoteTools(server, deps, grant, sessionId, json) {
     }
   );
 }
+function registerWorkClaimTools(server, deps, grant, sessionId, json) {
+  const attemptClaims = () => {
+    const resolved = exactAgentAttemptClaims(grant);
+    if (!resolved || resolved.sessionId !== sessionId) {
+      throw new Error("Exact signed work-claim attempt authority is required.");
+    }
+    return {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      ...resolved
+    };
+  };
+  const authorize = async () => {
+    await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+  };
+  server.registerTool(
+    "work_claim_upsert",
+    {
+      description: "Create or refresh one typed, non-exclusive claim describing this session's current external work. Claims are advisory evidence, never locks or authority. Use stable public identifiers only; never put credentials, tokens, or other secrets in claim fields. expectedRevision=0 creates a new active claim; refreshing an existing active claim requires its exact revision. Use a fresh operationId; an exact retry from a replacement attempt on the same logical turn replays safely.",
+      inputSchema: {
+        operationId: z43.string().uuid(),
+        expectedRevision: z43.number().int().min(0),
+        subjectNamespace: z43.string().min(1).max(WORK_CLAIM_NAMESPACE_MAX_BYTES),
+        subjectType: z43.enum([
+          "repository",
+          "branch",
+          "pull_request",
+          "issue",
+          "artifact",
+          "release",
+          "ci_run",
+          "other"
+        ]),
+        canonicalKey: z43.string().min(1).max(WORK_CLAIM_CANONICAL_KEY_MAX_BYTES),
+        displayLabel: z43.string().min(1).max(WORK_CLAIM_DISPLAY_LABEL_MAX_BYTES).optional(),
+        role: z43.enum(["working", "reviewing", "monitoring", "delivering"]),
+        versionKind: z43.enum([
+          "git_commit",
+          "branch_head",
+          "pull_request_head",
+          "artifact_version",
+          "release_version",
+          "ci_run",
+          "other"
+        ]).optional(),
+        versionValue: z43.string().min(1).max(WORK_CLAIM_VERSION_VALUE_MAX_BYTES).optional()
+      }
+    },
+    async ({
+      operationId,
+      expectedRevision,
+      subjectNamespace,
+      subjectType,
+      canonicalKey,
+      displayLabel,
+      role,
+      versionKind,
+      versionValue
+    }) => {
+      await authorize();
+      if (versionKind === void 0 !== (versionValue === void 0)) {
+        throw new Error("work_claim_upsert versionKind and versionValue must be supplied together");
+      }
+      return json(
+        await upsertWorkClaim(deps.db, {
+          ...attemptClaims(),
+          operationId,
+          expectedRevision,
+          subjectNamespace,
+          subjectType,
+          canonicalKey,
+          ...displayLabel === void 0 ? {} : { displayLabel },
+          role,
+          ...versionKind && versionValue ? { version: { kind: versionKind, value: versionValue } } : {}
+        })
+      );
+    }
+  );
+  server.registerTool(
+    "work_claim_release",
+    {
+      description: "Release one exact active claim owned by this session. This records an immutable receipt and does not affect other sessions claiming the same subject. Use a fresh operationId and the claim's exact revision.",
+      inputSchema: {
+        operationId: z43.string().uuid(),
+        claimId: z43.string().uuid(),
+        expectedRevision: z43.number().int().min(1),
+        reason: z43.enum([
+          "completed",
+          "cancelled",
+          "failed",
+          "superseded",
+          "no_longer_active",
+          "corrected",
+          "external_state_changed",
+          "other"
+        ])
+      }
+    },
+    async ({ operationId, claimId, expectedRevision, reason: reason2 }) => {
+      await authorize();
+      return json(
+        await releaseWorkClaim(deps.db, {
+          ...attemptClaims(),
+          operationId,
+          claimId,
+          expectedRevision,
+          reason: reason2
+        })
+      );
+    }
+  );
+}
 function registerPreferenceRegistryTools(server, deps, grant, json) {
   const attemptClaims = () => {
     const resolved = exactAgentAttemptClaims(grant);
@@ -21451,42 +21661,132 @@ function registerWorkspaceOrchestrationTools(server, deps, grant, can, callerSes
     server.registerTool(
       "sessions_list",
       {
-        description: `List compact high-level session status in this workspace. Defaults to creation order; use orderBy=updatedAt with decimal activity-revision updatedAfter/updatedThrough tokens for gap-free indexed incremental monitoring independent of application clocks. Cursors are opaque revision-fenced keysets. includeLastMessage is opt-in and never previews a human/API prompt whose turn was never claimed (still queued, or deleted/edited/cancelled before any claim): waiting work is represented by queuedPromptCount until the turn is claimed. Rendered previews share a deterministic ${SESSION_DISCOVERY_PREVIEW_MAX_BYTES}-byte UTF-8 aggregate budget, and omitted previews include a bounded session_events drill-down input (exact message type, direction=before, limit=1, monitoring summary). Use session_get for exact known targets and detailed resources/tools/settings. The list never returns full session objects or history.`,
+        description: `List compact high-level session status and advisory related-work evidence in this workspace. query searches semantic titles, active goals, and typed work claims; subject performs one exact provider-neutral claim lookup and ranks it ahead of text. Neither path searches initialMessage or grants access to a result. Claims are nonexclusive evidence, never locks or instructions. Relevance cursors are bound to normalized filters and a workspace activity-revision snapshot. Without search, the tool defaults to creation order; use orderBy=updatedAt with decimal activity-revision updatedAfter/updatedThrough tokens for gap-free indexed incremental monitoring independent of application clocks. includeLastMessage is opt-in and never previews a human/API prompt whose turn was never claimed (still queued, or deleted/edited/cancelled before any claim): waiting work is represented by queuedPromptCount until the turn is claimed. Rendered previews share a deterministic ${SESSION_DISCOVERY_PREVIEW_MAX_BYTES}-byte UTF-8 aggregate budget, and omitted previews include a bounded session_events drill-down input (exact message type, direction=before, limit=1, monitoring summary). Use session_get only when ordinary target authorization allows it. The list never returns full session objects, instructions, resources, tools, files, or history.`,
         inputSchema: {
           limit: z43.number().int().positive().max(100).optional(),
           cursor: z43.string().max(512).optional(),
           includeLastMessage: z43.boolean().optional(),
-          orderBy: z43.enum(["createdAt", "updatedAt"]).optional(),
-          updatedAfter: z43.string().max(64).optional()
+          orderBy: z43.enum(["createdAt", "updatedAt", "relevance"]).optional(),
+          updatedAfter: z43.string().max(64).optional(),
+          query: z43.string().max(WORK_DISCOVERY_QUERY_MAX_CHARS).optional(),
+          statuses: z43.array(
+            z43.enum([
+              "queued",
+              "running",
+              "idle",
+              "requires_action",
+              "recovering",
+              "waiting_capacity",
+              "failed",
+              "cancelled"
+            ])
+          ).max(8).optional(),
+          activeOnly: z43.boolean().optional(),
+          recentHours: z43.number().int().positive().max(WORK_DISCOVERY_RECENT_HOURS_MAX).optional(),
+          rootSessionId: z43.string().uuid().optional(),
+          parentSessionId: z43.string().uuid().nullable().optional(),
+          subject: z43.object({
+            namespace: z43.string().min(1).max(WORK_CLAIM_NAMESPACE_MAX_BYTES),
+            type: WorkClaimSubjectType,
+            canonicalKey: z43.string().min(1).max(WORK_CLAIM_CANONICAL_KEY_MAX_BYTES)
+          }).strict().optional(),
+          claimLimit: z43.number().int().positive().max(WORK_CLAIM_DISCOVERY_LIMIT).optional()
         }
       },
-      async ({ limit, cursor, includeLastMessage, orderBy: requestedOrderBy, updatedAfter }) => {
+      async ({
+        limit,
+        cursor,
+        includeLastMessage,
+        orderBy: requestedOrderBy,
+        updatedAfter,
+        query,
+        statuses,
+        activeOnly,
+        recentHours,
+        rootSessionId,
+        parentSessionId,
+        subject,
+        claimLimit
+      }) => {
         const authorizationScope = await requireSessionAuthorizationListScope(
           deps,
           grant,
           "first_party_mcp"
         );
+        const startedAtMs = performance.now();
+        const mode = subject ? "subject" : query?.trim() ? "query" : "browse";
+        const metricAuthorizationScope = authorizationScope?.kind === "scoped" ? "scoped" : "workspace";
         const decodedCursor = cursor ? decodeSessionDiscoveryCursor(cursor) : void 0;
-        const orderBy = requestedOrderBy ?? decodedCursor?.orderBy ?? "createdAt";
-        if (decodedCursor && decodedCursor.orderBy !== orderBy) {
-          throw new Error("sessions_list cursor order does not match orderBy");
-        }
-        const normalizedUpdatedAfter = updatedAfter !== void 0 ? normalizeSessionDiscoveryRevision(updatedAfter, "updatedAfter") : decodedCursor?.updatedAfter ?? void 0;
-        if (normalizedUpdatedAfter !== void 0 && orderBy !== "updatedAt") {
-          throw new Error("sessions_list updatedAfter requires orderBy=updatedAt");
+        const relevanceRequested = Boolean(query?.trim() || subject);
+        if (relevanceRequested && !deps.settings.workDiscoveryEnabled) {
+          observeWorkDiscovery(deps.observability, {
+            surface: "first_party_mcp",
+            mode,
+            outcome: "disabled",
+            authorizationScope: metricAuthorizationScope,
+            durationMs: performance.now() - startedAtMs,
+            responseBytes: 0,
+            resultCount: 0,
+            overlapCount: 0,
+            matchCounts: {}
+          });
+          throw new Error("sessions_list work discovery is disabled by the operator");
         }
-        if (decodedCursor && decodedCursor.updatedAfter !== (normalizedUpdatedAfter ?? null)) {
-          throw new Error("sessions_list cursor does not match updatedAfter");
+        try {
+          const orderBy = requestedOrderBy ?? decodedCursor?.orderBy ?? (relevanceRequested ? "relevance" : "createdAt");
+          if (decodedCursor && decodedCursor.orderBy !== orderBy) {
+            throw new Error("sessions_list cursor order does not match orderBy");
+          }
+          const normalizedUpdatedAfter = updatedAfter !== void 0 ? normalizeSessionDiscoveryRevision(updatedAfter, "updatedAfter") : decodedCursor?.updatedAfter ?? void 0;
+          if (normalizedUpdatedAfter !== void 0 && orderBy !== "updatedAt") {
+            throw new Error("sessions_list updatedAfter requires orderBy=updatedAt");
+          }
+          if (decodedCursor && decodedCursor.updatedAfter !== (normalizedUpdatedAfter ?? null)) {
+            throw new Error("sessions_list cursor does not match updatedAfter");
+          }
+          const page = await listSessionDiscoverySummaries(deps.db, grant.workspaceId, {
+            limit: boundedSessionDiscoveryLimit(limit),
+            ...decodedCursor ? { cursor: decodedCursor } : {},
+            includeLastMessage: includeLastMessage === true,
+            orderBy,
+            ...normalizedUpdatedAfter ? { updatedAfter: normalizedUpdatedAfter } : {},
+            ...query?.trim() ? { query } : {},
+            ...statuses ? { statuses } : {},
+            activeOnly: activeOnly === true,
+            ...recentHours !== void 0 ? { recentHours } : {},
+            ...rootSessionId ? { rootSessionId } : {},
+            ...parentSessionId !== void 0 ? { parentSessionId } : {},
+            ...subject ? { subject } : {},
+            ...claimLimit !== void 0 ? { claimLimit } : {},
+            includeWorkDiscovery: deps.settings.workDiscoveryEnabled,
+            subjectId: grant.subjectId,
+            ...authorizationScope ? { authorizationScope } : {}
+          });
+          const result = capSessionDiscoveryPage(page, includeLastMessage === true);
+          observeWorkDiscovery(deps.observability, {
+            surface: "first_party_mcp",
+            mode,
+            outcome: result.sessions.length === 0 ? "empty" : "ok",
+            authorizationScope: metricAuthorizationScope,
+            durationMs: performance.now() - startedAtMs,
+            responseBytes: result.bytes,
+            ...summarizeWorkDiscoveryRows(result.sessions)
+          });
+          return json(result);
+        } catch (error) {
+          observeWorkDiscovery(deps.observability, {
+            surface: "first_party_mcp",
+            mode,
+            outcome: "error",
+            authorizationScope: metricAuthorizationScope,
+            durationMs: performance.now() - startedAtMs,
+            responseBytes: 0,
+            resultCount: 0,
+            overlapCount: 0,
+            matchCounts: {}
+          });
+          throw error;
         }
-        const page = await listSessionDiscoverySummaries(deps.db, grant.workspaceId, {
-          limit: boundedSessionDiscoveryLimit(limit),
-          ...decodedCursor ? { cursor: decodedCursor } : {},
-          includeLastMessage: includeLastMessage === true,
-          orderBy,
-          ...normalizedUpdatedAfter ? { updatedAfter: normalizedUpdatedAfter } : {},
-          ...authorizationScope ? { authorizationScope } : {}
-        });
-        return json(capSessionDiscoveryPage(page, includeLastMessage === true));
       }
     );
     server.registerTool(
@@ -22699,10 +22999,12 @@ function boundedSessionDiscoveryLimit(limit) {
   return Math.min(SESSION_DISCOVERY_MAX_LIMIT, Math.max(1, Math.floor(limit)));
 }
 function encodeSessionDiscoveryCursor(cursor) {
+  const relevance = cursor.orderBy === "relevance";
   return Buffer.from(
     JSON.stringify({
-      v: 2,
+      v: relevance ? 3 : 2,
       orderBy: cursor.orderBy,
+      ...relevance ? { sortRank: cursor.sortRank, filterHash: cursor.filterHash } : {},
       sortRevision: cursor.sortRevision,
       sortAt: cursor.sortAt,
       id: cursor.id,
@@ -22743,28 +23045,40 @@ function decodeSessionDiscoveryCursor(value) {
       );
       return {
         orderBy: "createdAt",
+        sortRank: null,
         sortRevision: "0",
         sortAt: createdAt,
         id: parsed.id,
         snapshotAt: createdAt,
         snapshotRevision: "0",
-        updatedAfter: null
+        updatedAfter: null,
+        filterHash: null
       };
     }
     if (parsed.v === 1 && parsed.orderBy === "createdAt" && typeof parsed.sortAt === "string" && typeof parsed.snapshotAt === "string" && parsed.updatedAfter === null && typeof parsed.id === "string" && SESSION_DISCOVERY_UUID.test(parsed.id)) {
       return {
         orderBy: "createdAt",
+        sortRank: null,
         sortRevision: "0",
         sortAt: normalizeSessionDiscoveryTimestamp(parsed.sortAt, "cursor sortAt"),
         id: parsed.id,
         snapshotAt: normalizeSessionDiscoveryTimestamp(parsed.snapshotAt, "cursor snapshotAt"),
         snapshotRevision: "0",
-        updatedAfter: null
+        updatedAfter: null,
+        filterHash: null
       };
     }
-    if (parsed.v !== 2 || parsed.orderBy !== "createdAt" && parsed.orderBy !== "updatedAt" || typeof parsed.sortRevision !== "string" || typeof parsed.sortAt !== "string" || typeof parsed.snapshotAt !== "string" || typeof parsed.snapshotRevision !== "string" || parsed.updatedAfter !== null && typeof parsed.updatedAfter !== "string" || typeof parsed.id !== "string" || !SESSION_DISCOVERY_UUID.test(parsed.id)) {
+    const isV2 = parsed.v === 2;
+    const isV3 = parsed.v === 3;
+    if (!isV2 && !isV3 || isV2 && parsed.orderBy !== "createdAt" && parsed.orderBy !== "updatedAt" || isV3 && parsed.orderBy !== "relevance" || typeof parsed.sortRevision !== "string" || typeof parsed.sortAt !== "string" || typeof parsed.snapshotAt !== "string" || typeof parsed.snapshotRevision !== "string" || parsed.updatedAfter !== null && typeof parsed.updatedAfter !== "string" || typeof parsed.id !== "string" || !SESSION_DISCOVERY_UUID.test(parsed.id)) {
       throw new Error("invalid cursor fields");
     }
+    if (isV3 && (!Number.isSafeInteger(parsed.sortRank) || parsed.sortRank < 0 || typeof parsed.filterHash !== "string" || !/^[0-9a-f]{64}$/.test(parsed.filterHash))) {
+      throw new Error("invalid relevance cursor fields");
+    }
+    if (isV2 && (parsed.sortRank !== void 0 || parsed.filterHash !== void 0)) {
+      throw new Error("chronological cursor cannot carry relevance fields");
+    }
     const sortAt = normalizeSessionDiscoveryTimestamp(parsed.sortAt, "cursor sortAt");
     const snapshotAt = normalizeSessionDiscoveryTimestamp(parsed.snapshotAt, "cursor snapshotAt");
     const sortRevision = normalizeSessionDiscoveryRevision(
@@ -22782,14 +23096,17 @@ function decodeSessionDiscoveryCursor(value) {
     if (parsed.orderBy === "createdAt" && (sortRevision !== "0" || snapshotRevision !== "0")) {
       throw new Error("creation cursor cannot carry activity revisions");
     }
+    const orderBy = isV3 ? "relevance" : parsed.orderBy;
     return {
-      orderBy: parsed.orderBy,
+      orderBy,
+      sortRank: isV3 ? parsed.sortRank : null,
       sortRevision,
       sortAt,
       id: parsed.id,
       snapshotAt,
       snapshotRevision,
-      updatedAfter: normalizedUpdatedAfter
+      updatedAfter: normalizedUpdatedAfter,
+      filterHash: isV3 ? parsed.filterHash : null
     };
   } catch {
     throw new Error("sessions_list cursor is invalid");
@@ -22857,6 +23174,7 @@ function capSessionDiscoveryPage(page, includeLastMessage) {
       } : null,
       queuedPromptCount: session.queuedPromptCount,
       children: session.treeStats,
+      relatedWork: session.workDiscovery,
       ...includeLastMessage ? {
         latestMessage: session.latestMessage ? {
           type: session.latestMessage.type,
@@ -22907,12 +23225,14 @@ function capSessionDiscoveryPage(page, includeLastMessage) {
     const sourceLast = lastKept ? page.sessions.find((session) => session.id === lastKept.id) : void 0;
     const nextCursor = droppedForByteCap ? sourceLast ? encodeSessionDiscoveryCursor({
       orderBy: page.orderBy,
+      sortRank: sourceLast.sortRank,
       sortRevision: sourceLast.sortRevision,
       sortAt: sourceLast.sortAt,
       id: sourceLast.id,
       snapshotAt: page.snapshotAt,
       snapshotRevision: page.snapshotRevision,
-      updatedAfter: page.updatedAfter
+      updatedAfter: page.updatedAfter,
+      filterHash: page.filterHash
     }) : null : page.nextCursor ? encodeSessionDiscoveryCursor(page.nextCursor) : null;
     const result2 = {
       sessions: kept,
@@ -46725,6 +47045,15 @@ import {
   UpdateSessionToolPolicyRequest,
   ViewerHeartbeatRequest,
   WORKSPACE_CONTROL_ACTOR_MAX_BYTES,
+  WORK_CLAIM_CANONICAL_KEY_MAX_BYTES as WORK_CLAIM_CANONICAL_KEY_MAX_BYTES2,
+  WORK_CLAIM_DISCOVERY_LIMIT as WORK_CLAIM_DISCOVERY_LIMIT2,
+  WORK_CLAIM_NAMESPACE_MAX_BYTES as WORK_CLAIM_NAMESPACE_MAX_BYTES2,
+  WORK_DISCOVERY_QUERY_MAX_CHARS as WORK_DISCOVERY_QUERY_MAX_CHARS2,
+  WORK_DISCOVERY_RECENT_HOURS_MAX as WORK_DISCOVERY_RECENT_HOURS_MAX2,
+  WorkClaimSubjectFilter as WorkClaimSubjectFilterSchema,
+  WorkClaimSubjectType as WorkClaimSubjectType2,
+  normalizeWorkClaimCanonicalKey,
+  normalizeWorkClaimNamespace,
   workspaceControlUtf8Bytes
 } from "@opengeni/contracts";
 import { streamTokenDegraded } from "@opengeni/config";
@@ -48178,60 +48507,127 @@ function registerSessionRoutes(app, deps) {
       throw sessionAuthorizationHttpError(error);
     }
     const query = agentTopologyQuery(c.req.query());
-    const page = await listSessionDiscoverySummaries2(db, workspaceId, {
-      limit: query.limit,
-      orderBy: "updatedAt",
-      subjectId: grant.subjectId,
-      ...query.cursor ? { cursor: query.cursor } : {},
-      ...query.search ? { search: query.search } : { parentSessionId: query.parentSessionId },
-      ...authorizationScope ? { authorizationScope } : {}
-    });
-    const ancestorPaths = query.search ? await listSessionDiscoveryAncestorPaths(
-      db,
-      workspaceId,
-      page.sessions.map((session) => session.id),
-      authorizationScope ?? void 0
-    ) : /* @__PURE__ */ new Map();
-    const sessions = page.sessions.map((session) => {
-      const blocker = session.effectiveControl.primaryBlocker;
-      return {
-        id: session.id,
-        title: session.title,
-        titleTruncated: session.titleOriginalChars !== null && session.titleOriginalChars > Array.from(session.title ?? "").length,
-        parentSessionId: session.parentSessionId,
-        rootSessionId: session.rootSessionId,
-        nestedAgentDepth: session.nestedAgentDepth,
-        ancestorPath: (ancestorPaths.get(session.id) ?? []).map((ancestor) => ({
-          id: ancestor.id,
-          title: ancestor.title,
-          titleTruncated: ancestor.titleOriginalChars !== null && ancestor.titleOriginalChars > Array.from(ancestor.title ?? "").length
-        })),
-        status: session.status,
-        pause: {
-          state: session.effectiveControl.state,
-          additionalBlockerCount: session.effectiveControl.additionalBlockerCount,
-          source: blocker ? {
-            kind: blocker.kind,
-            ...blocker.sessionId ? { sessionId: blocker.sessionId } : {},
-            displayName: blocker.displayName,
-            displayNameTruncated: blocker.displayNameOriginalChars > Array.from(blocker.displayName).length
-          } : null
-        },
-        children: session.treeStats,
-        createdAt: session.createdAt,
-        updatedAt: session.updatedAt
+    const startedAtMs = performance.now();
+    const mode = query.subject ? "subject" : query.query ? "query" : "browse";
+    const metricAuthorizationScope = authorizationScope?.kind === "scoped" ? "scoped" : "workspace";
+    if ((query.query || query.subject) && !settings.workDiscoveryEnabled) {
+      observeWorkDiscovery(deps.observability, {
+        surface: "agent_topology",
+        mode,
+        outcome: "disabled",
+        authorizationScope: metricAuthorizationScope,
+        durationMs: performance.now() - startedAtMs,
+        responseBytes: 0,
+        resultCount: 0,
+        overlapCount: 0,
+        matchCounts: {}
+      });
+      throw new HTTPException53(503, {
+        message: "Agent work discovery is disabled by the operator."
+      });
+    }
+    try {
+      const orderBy = query.query || query.subject ? "relevance" : "updatedAt";
+      const page = await listSessionDiscoverySummaries2(db, workspaceId, {
+        limit: query.limit,
+        orderBy,
+        subjectId: grant.subjectId,
+        ...query.cursor ? { cursor: query.cursor } : {},
+        ...query.parentSessionId !== void 0 ? { parentSessionId: query.parentSessionId } : {},
+        ...query.rootSessionId ? { rootSessionId: query.rootSessionId } : {},
+        ...query.query ? { query: query.query } : {},
+        ...query.statuses ? { statuses: query.statuses } : {},
+        activeOnly: query.activeOnly,
+        ...query.recentHours !== void 0 ? { recentHours: query.recentHours } : {},
+        ...query.subject ? { subject: query.subject } : {},
+        ...query.claimLimit !== void 0 ? { claimLimit: query.claimLimit } : {},
+        includeWorkDiscovery: settings.workDiscoveryEnabled,
+        ...authorizationScope ? { authorizationScope } : {}
+      });
+      const ancestorPaths = query.query || query.subject ? await listSessionDiscoveryAncestorPaths(
+        db,
+        workspaceId,
+        page.sessions.map((session) => session.id),
+        authorizationScope ?? void 0,
+        grant.subjectId
+      ) : /* @__PURE__ */ new Map();
+      const sessions = page.sessions.map((session) => {
+        const blocker = session.effectiveControl.primaryBlocker;
+        return {
+          id: session.id,
+          title: session.title,
+          titleTruncated: session.titleOriginalChars !== null && session.titleOriginalChars > Array.from(session.title ?? "").length,
+          parentSessionId: session.parentSessionId,
+          rootSessionId: session.rootSessionId,
+          nestedAgentDepth: session.nestedAgentDepth,
+          ancestorPath: (ancestorPaths.get(session.id) ?? []).map((ancestor) => ({
+            id: ancestor.id,
+            title: ancestor.title,
+            titleTruncated: ancestor.titleOriginalChars !== null && ancestor.titleOriginalChars > Array.from(ancestor.title ?? "").length
+          })),
+          status: session.status,
+          goal: session.goal ? {
+            status: session.goal.status,
+            summary: session.goal.text,
+            summaryTruncated: session.goal.textOriginalChars > Array.from(session.goal.text).length
+          } : null,
+          pause: {
+            state: session.effectiveControl.state,
+            additionalBlockerCount: session.effectiveControl.additionalBlockerCount,
+            source: blocker ? {
+              kind: blocker.kind,
+              ...blocker.sessionId ? { sessionId: blocker.sessionId } : {},
+              displayName: blocker.displayName,
+              displayNameTruncated: blocker.displayNameOriginalChars > Array.from(blocker.displayName).length
+            } : null
+          },
+          children: session.treeStats,
+          relatedWork: session.workDiscovery,
+          createdAt: session.createdAt,
+          updatedAt: session.updatedAt
+        };
+      });
+      const response = {
+        sessions,
+        total: page.total,
+        hasMore: page.hasMore,
+        humanAdvisoriesEnabled: settings.workDiscoveryEnabled && settings.workDiscoveryHumanAdvisoriesEnabled,
+        nextCursor: page.nextCursor ? encodeAgentTopologyCursor({
+          cursor: page.nextCursor,
+          parentSessionId: query.parentSessionId === void 0 ? "all" : query.parentSessionId,
+          rootSessionId: query.rootSessionId ?? null,
+          query: query.query ?? null,
+          statuses: query.statuses ?? [],
+          activeOnly: query.activeOnly,
+          recentHours: query.recentHours ?? null,
+          subject: query.subject ?? null,
+          claimLimit: query.claimLimit ?? null
+        }) : null
       };
-    });
-    return c.json({
-      sessions,
-      total: page.total,
-      hasMore: page.hasMore,
-      nextCursor: page.nextCursor ? encodeAgentTopologyCursor({
-        cursor: page.nextCursor,
-        parentSessionId: query.parentSessionId,
-        search: query.search ?? null
-      }) : null
-    });
+      observeWorkDiscovery(deps.observability, {
+        surface: "agent_topology",
+        mode,
+        outcome: sessions.length === 0 ? "empty" : "ok",
+        authorizationScope: metricAuthorizationScope,
+        durationMs: performance.now() - startedAtMs,
+        responseBytes: Buffer.byteLength(JSON.stringify(response), "utf8"),
+        ...summarizeWorkDiscoveryRows(sessions)
+      });
+      return c.json(response);
+    } catch (error) {
+      observeWorkDiscovery(deps.observability, {
+        surface: "agent_topology",
+        mode,
+        outcome: "error",
+        authorizationScope: metricAuthorizationScope,
+        durationMs: performance.now() - startedAtMs,
+        responseBytes: 0,
+        resultCount: 0,
+        overlapCount: 0,
+        matchCounts: {}
+      });
+      throw error;
+    }
   });
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
@@ -51498,7 +51894,7 @@ function sessionListQuery(query, allowCursor = true) {
   };
 }
 function encodeAgentTopologyCursor(value) {
-  return Buffer.from(JSON.stringify({ v: 1, ...value }), "utf8").toString("base64url");
+  return Buffer.from(JSON.stringify({ v: 2, ...value }), "utf8").toString("base64url");
 }
 function decodeAgentTopologyCursor(value) {
   if (value.length > 2048) {
@@ -51507,23 +51903,85 @@ function decodeAgentTopologyCursor(value) {
     });
   }
   try {
-    const parsed = z13.object({
+    const decoded2 = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+    const legacy = z13.object({
       v: z13.literal(1),
       parentSessionId: z13.string().uuid().nullable(),
-      search: z13.string().max(200).nullable(),
+      search: z13.string().max(WORK_DISCOVERY_QUERY_MAX_CHARS2).nullable(),
       cursor: z13.object({
-        orderBy: z13.enum(["createdAt", "updatedAt"]),
+        orderBy: z13.literal("updatedAt"),
         sortRevision: z13.string().max(64),
         sortAt: z13.string().max(64),
         id: z13.string().uuid(),
         snapshotAt: z13.string().max(64),
         snapshotRevision: z13.string().max(64),
-        updatedAfter: z13.string().max(64).nullable()
+        updatedAfter: z13.null()
       })
-    }).parse(JSON.parse(Buffer.from(value, "base64url").toString("utf8")));
-    if (parsed.cursor.orderBy !== "updatedAt" || parsed.cursor.updatedAfter !== null || !/^(?:0|[1-9]\d*)$/.test(parsed.cursor.sortRevision) || !/^(?:0|[1-9]\d*)$/.test(parsed.cursor.snapshotRevision) || BigInt(parsed.cursor.sortRevision) > 9223372036854775807n || BigInt(parsed.cursor.snapshotRevision) > 9223372036854775807n || Number.isNaN(Date.parse(parsed.cursor.sortAt)) || Number.isNaN(Date.parse(parsed.cursor.snapshotAt))) {
+    }).safeParse(decoded2);
+    if (legacy.success) {
+      if (legacy.data.search !== null) {
+        throw new Error("legacy search cursor is not relevance-fenced");
+      }
+      const cursor = {
+        ...legacy.data.cursor,
+        sortRank: null,
+        filterHash: null
+      };
+      return {
+        cursor,
+        parentSessionId: legacy.data.parentSessionId,
+        rootSessionId: null,
+        query: null,
+        statuses: [],
+        activeOnly: false,
+        recentHours: null,
+        subject: null,
+        claimLimit: null
+      };
+    }
+    const parsed = z13.object({
+      v: z13.literal(2),
+      parentSessionId: z13.union([z13.string().uuid(), z13.literal("all"), z13.null()]),
+      rootSessionId: z13.string().uuid().nullable(),
+      query: z13.string().max(WORK_DISCOVERY_QUERY_MAX_CHARS2).nullable(),
+      statuses: z13.array(
+        z13.enum([
+          "queued",
+          "running",
+          "idle",
+          "requires_action",
+          "recovering",
+          "waiting_capacity",
+          "failed",
+          "cancelled"
+        ])
+      ).max(8),
+      activeOnly: z13.boolean(),
+      recentHours: z13.number().int().positive().max(WORK_DISCOVERY_RECENT_HOURS_MAX2).nullable(),
+      subject: z13.object({
+        namespace: z13.string().min(1).max(WORK_CLAIM_NAMESPACE_MAX_BYTES2),
+        type: WorkClaimSubjectType2,
+        canonicalKey: z13.string().min(1).max(WORK_CLAIM_CANONICAL_KEY_MAX_BYTES2)
+      }).strict().nullable(),
+      claimLimit: z13.number().int().positive().max(WORK_CLAIM_DISCOVERY_LIMIT2).nullable(),
+      cursor: z13.object({
+        orderBy: z13.enum(["updatedAt", "relevance"]),
+        sortRank: z13.number().int().nonnegative().nullable(),
+        sortRevision: z13.string().max(64),
+        sortAt: z13.string().max(64),
+        id: z13.string().uuid(),
+        snapshotAt: z13.string().max(64),
+        snapshotRevision: z13.string().max(64),
+        updatedAfter: z13.null(),
+        filterHash: z13.string().regex(/^[0-9a-f]{64}$/).nullable()
+      })
+    }).parse(decoded2);
+    if (!/^(?:0|[1-9]\d*)$/.test(parsed.cursor.sortRevision) || !/^(?:0|[1-9]\d*)$/.test(parsed.cursor.snapshotRevision) || BigInt(parsed.cursor.sortRevision) > 9223372036854775807n || BigInt(parsed.cursor.snapshotRevision) > 9223372036854775807n || Number.isNaN(Date.parse(parsed.cursor.sortAt)) || Number.isNaN(Date.parse(parsed.cursor.snapshotAt))) {
       throw new Error("invalid topology cursor fields");
     }
+    if (parsed.cursor.orderBy === "relevance" && (parsed.cursor.sortRank === null || parsed.cursor.filterHash === null) || parsed.cursor.orderBy === "updatedAt" && (parsed.cursor.sortRank !== null || parsed.cursor.filterHash !== null)) {
+      throw new Error("invalid topology cursor relevance fields");
+    }
     return parsed;
   } catch {
     throw new HTTPException53(400, {
@@ -51545,20 +52003,108 @@ function agentTopologyQuery(query) {
       message: 'parentSessionId must be a session id or the literal "null"'
     });
   }
-  const parentSessionId = rawParent === void 0 || rawParent === "null" ? null : rawParent;
-  const search = query.search?.trim();
-  if (search && search.length > 200) {
+  const rootSessionId = query.rootSessionId?.trim();
+  if (rootSessionId && !z13.string().uuid().safeParse(rootSessionId).success) {
+    throw new HTTPException53(400, { message: "rootSessionId must be a session id" });
+  }
+  const normalizeSearchQuery = (value) => {
+    if (value === void 0) return void 0;
+    const canonical = value.normalize("NFKC");
+    if (/[\u0000-\u001f\u007f-\u009f]/u.test(canonical)) {
+      throw new HTTPException53(400, { message: "query must not contain control characters" });
+    }
+    const normalized = canonical.trim().replace(/\s+/gu, " ").toLowerCase();
+    if (!normalized) return void 0;
+    if (Array.from(normalized).length > WORK_DISCOVERY_QUERY_MAX_CHARS2) {
+      throw new HTTPException53(400, {
+        message: `query must be at most ${WORK_DISCOVERY_QUERY_MAX_CHARS2} characters`
+      });
+    }
+    return normalized;
+  };
+  const requestedQuery = normalizeSearchQuery(query.query);
+  const legacySearch = normalizeSearchQuery(query.search);
+  const searchQuery = requestedQuery ?? legacySearch;
+  if (requestedQuery && legacySearch && requestedQuery !== legacySearch) {
+    throw new HTTPException53(400, { message: "query and legacy search must match" });
+  }
+  const statuses = query.statuses ? [
+    ...new Set(
+      query.statuses.split(",").map((status) => status.trim()).filter(Boolean)
+    )
+  ].sort() : [];
+  const parsedStatuses = z13.array(
+    z13.enum([
+      "queued",
+      "running",
+      "idle",
+      "requires_action",
+      "recovering",
+      "waiting_capacity",
+      "failed",
+      "cancelled"
+    ])
+  ).max(8).safeParse(statuses);
+  if (!parsedStatuses.success) {
+    throw new HTTPException53(400, { message: "statuses contains an unsupported lifecycle state" });
+  }
+  const activeOnly = query.activeOnly === "true";
+  if (query.activeOnly !== void 0 && query.activeOnly !== "true" && query.activeOnly !== "false") {
+    throw new HTTPException53(400, { message: "activeOnly must be true or false" });
+  }
+  const recentHours = query.recentHours === void 0 ? void 0 : Number(query.recentHours);
+  if (recentHours !== void 0 && (!Number.isSafeInteger(recentHours) || recentHours < 1 || recentHours > WORK_DISCOVERY_RECENT_HOURS_MAX2)) {
     throw new HTTPException53(400, {
-      message: "search must be at most 200 characters"
+      message: `recentHours must be an integer between 1 and ${WORK_DISCOVERY_RECENT_HOURS_MAX2}`
+    });
+  }
+  const subjectFields = [query.subjectNamespace, query.subjectType, query.subjectKey];
+  if (subjectFields.some((value) => value !== void 0) && subjectFields.some((value) => !value)) {
+    throw new HTTPException53(400, {
+      message: "subjectNamespace, subjectType, and subjectKey must be supplied together"
     });
   }
-  if (search && rawParent !== void 0) {
+  const parsedSubject = subjectFields.every((value) => value !== void 0) ? WorkClaimSubjectFilterSchema.safeParse({
+    namespace: normalizeWorkClaimNamespace(query.subjectNamespace),
+    type: query.subjectType,
+    canonicalKey: normalizeWorkClaimCanonicalKey(query.subjectKey)
+  }) : null;
+  if (parsedSubject && !parsedSubject.success) {
+    throw new HTTPException53(400, { message: "exact subject filter is invalid" });
+  }
+  const subject = parsedSubject?.success ? parsedSubject.data : void 0;
+  if (searchQuery && subject) {
+    throw new HTTPException53(400, { message: "query cannot be combined with an exact subject" });
+  }
+  const relevanceRequested = Boolean(searchQuery || subject);
+  const parentSessionId = rawParent === void 0 ? relevanceRequested ? void 0 : null : rawParent === "null" ? null : rawParent;
+  const claimLimit = query.claimLimit === void 0 ? void 0 : Number(query.claimLimit);
+  if (claimLimit !== void 0 && (!Number.isSafeInteger(claimLimit) || claimLimit < 1 || claimLimit > WORK_CLAIM_DISCOVERY_LIMIT2)) {
     throw new HTTPException53(400, {
-      message: "search cannot be combined with parentSessionId"
+      message: `claimLimit must be an integer between 1 and ${WORK_CLAIM_DISCOVERY_LIMIT2}`
     });
   }
   const envelope = query.cursor ? decodeAgentTopologyCursor(query.cursor) : void 0;
-  if (envelope && (envelope.parentSessionId !== parentSessionId || envelope.search !== (search || null))) {
+  const expectedEnvelope = {
+    parentSessionId: parentSessionId === void 0 ? "all" : parentSessionId,
+    rootSessionId: rootSessionId ?? null,
+    query: searchQuery || null,
+    statuses: parsedStatuses.data,
+    activeOnly,
+    recentHours: recentHours ?? null,
+    subject: subject ?? null,
+    claimLimit: claimLimit ?? null
+  };
+  if (envelope && JSON.stringify({
+    parentSessionId: envelope.parentSessionId,
+    rootSessionId: envelope.rootSessionId,
+    query: envelope.query,
+    statuses: envelope.statuses,
+    activeOnly: envelope.activeOnly,
+    recentHours: envelope.recentHours,
+    subject: envelope.subject,
+    claimLimit: envelope.claimLimit
+  }) !== JSON.stringify(expectedEnvelope)) {
     throw new HTTPException53(400, {
       message: "agent topology cursor does not match its filters"
     });
@@ -51566,7 +52112,13 @@ function agentTopologyQuery(query) {
   return {
     limit,
     parentSessionId,
-    search: search || void 0,
+    rootSessionId: rootSessionId || void 0,
+    query: searchQuery || void 0,
+    statuses: parsedStatuses.data.length > 0 ? parsedStatuses.data : void 0,
+    activeOnly,
+    recentHours,
+    subject,
+    claimLimit,
     cursor: envelope?.cursor
   };
 }
@@ -65379,4 +65931,4 @@ export {
   withDefaultEnabledCapabilityMcpTools,
   workflowIdForSession3 as workflowIdForSession
 };
-//# sourceMappingURL=chunk-L7GVVSSQ.js.map
+//# sourceMappingURL=chunk-QESX7HDK.js.map