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

package/src/mcp/server.ts

@@ -14,6 +14,7 @@ import {
   stableJson,
   compactSessionEventResult,
   sessionEventLatestClassToSemanticClass,
+  MemorySlackPublicationDistribution,
   SessionMcpCredentialUpdateInput,
   ToolAuthNeededPayload,
   VariableSetVariableName,
@@ -38,6 +39,7 @@ import {
   SESSION_GOAL_SUCCESS_CRITERIA_MAX_BYTES,
   SESSION_GOAL_TEXT_MAX_BYTES,
   SESSION_INSTRUCTIONS_MAX_CHARACTERS,
+  SESSION_TITLE_MAX_CHARACTERS,
   MAX_SELECTED_VARIABLE_SETS,
   sessionGoalUtf8Bytes,
   TASK_NOTE_LIST_DEFAULT_LIMIT,
@@ -45,6 +47,16 @@ 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,
+  type WorkClaimSubjectFilter,
+  type SessionStatus,
   SubmitHumanInputResponseRequest,
 } from "@opengeni/contracts";
 import {
@@ -80,6 +92,8 @@ import {
   readVariableSetSecretAtomically,
   recordSyncedSocialPosts,
   listVariableSets,
+  MEMORY_CORRECT_TOOL_DESCRIPTION,
+  MEMORY_SAVE_TOOL_DESCRIPTION,
   MEMORY_SEARCH_TOOL_DESCRIPTION,
   requireScheduledTask,
   requireSession,
@@ -104,10 +118,16 @@ import {
   createTaskNote,
   listTaskNotes,
   replaceTaskNote,
+  releaseWorkClaim,
+  upsertWorkClaim,
   acceptSessionHumanInputResponse,
   HumanInputResponseValidationError,
 } from "@opengeni/db";
-import { appendAndPublishTurnEventsFenced, publishDurableSessionEvents } from "@opengeni/events";
+import {
+  appendAndPublishEvents,
+  appendAndPublishTurnEventsFenced,
+  publishDurableSessionEvents,
+} from "@opengeni/events";
 import { allowedFirstPartyMcpToolsForSession, codemodeWorkspaceUrl } from "@opengeni/config";
 import {
   createSignedState,
@@ -129,12 +149,14 @@ import {
   authorizedSocialConnectionsForGrant,
   authorizedAtlassianConnectionsForGrant,
   buildCapabilityCatalog,
+  correctWorkspaceMemoryWithSlackPublication,
   nativeConnectionCapabilityRecommendations,
   requireLiveAgentAttemptAuthorization,
   requireSessionAuthorization,
   requireSessionAuthorizationListScope,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
+  saveWorkspaceMemoryWithSlackPublication,
   searchCapabilityCatalogItems,
   type ResolvedSessionAuthorization,
 } from "@opengeni/core";
@@ -179,6 +201,7 @@ import {
   ScheduledTaskSyncError,
   syncCreatedScheduledTask,
   syncUpdatedScheduledTask,
+  validateScheduledTaskMachineTarget,
   validateScheduledTaskTarget,
   updateScheduledTaskForApi,
   validatedScheduledTaskUpdate,
@@ -216,11 +239,13 @@ import {
   SESSION_EVENT_MCP_MAX_BYTES,
 } from "./session-view";
 import {
+  SESSION_WAIT_COMPLETION_EVENT_TYPES,
   SESSION_WAIT_DEFAULT_SECONDS,
   SESSION_WAIT_EVENT_TYPES,
   SESSION_WAIT_EVENTS_PER_TARGET,
   SESSION_WAIT_MAX_SECONDS,
   SESSION_WAIT_MAX_TARGETS,
+  sessionWaitCompletionEventMatches,
   waitForSessionChanges,
 } from "./session-wait";
 import {
@@ -251,6 +276,7 @@ import { registerCompanyProfileAgentAdminTools } from "./company-profile-agent-a
 import { registerRememberTools } from "./remember";
 import { mintSandboxCodemodeToken } from "@opengeni/runtime/sandbox";
 import { deleteScheduledTaskWithDurableCleanup } from "../scheduled-task-deletion";
+import { observeWorkDiscovery, summarizeWorkDiscoveryRows } from "../work-discovery-observability";
 
 export type McpServerOptions = {
   // Origin of the HTTP request that reached the MCP route. Browser-oriented
@@ -262,6 +288,12 @@ export type McpServerOptions = {
 
 const ORCHESTRATION_FAILURE_CODE_MAX_LENGTH = 128;
 const ORCHESTRATION_FAILURE_MESSAGE_MAX_UTF8_BYTES = 1_024;
+// Keep pathological raw MCP payloads away from Unicode normalization while
+// leaving the shared DB normalizer authoritative for the exact post-NFKC
+// code-point limit. The multiplier admits supplementary-plane characters,
+// decomposed forms, and ordinary whitespace folding without reopening the
+// API-wide request-body ceiling for this 200-code-point field.
+const MCP_DISCOVERY_QUERY_MAX_UTF16_CODE_UNITS = WORK_DISCOVERY_QUERY_MAX_CHARS * 8;
 
 type OrchestrationToolName = "session_create" | "session_send_message";
 
@@ -396,9 +428,6 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   goal_complete: { sessionRequired: true, allOf: ["goals:manage"] },
   goal_pause: { sessionRequired: true, allOf: ["goals:manage"] },
   memory_search: { sessionRequired: true, allOf: ["documents:search"] },
-  // Retired: never registered, so these are never consulted. The map must stay
-  // total over the tool-name union, which still carries both names so that
-  // previously written scheduled-task snapshots keep parsing.
   memory_save: { sessionRequired: true, allOf: ["documents:search"] },
   memory_correct: { sessionRequired: true, allOf: ["documents:search"] },
   preference_registry_summary: {
@@ -410,6 +439,8 @@ const 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: {
@@ -791,6 +822,9 @@ export function buildOpenGeniMcpServer(
   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,
@@ -1696,6 +1730,14 @@ export function buildOpenGeniMcpServer(
             agentConfig: task.agentConfig,
             missingTargetStatus: 404,
           });
+          await validateScheduledTaskMachineTarget({
+            settings: deps.settings,
+            db: deps.db,
+            grant,
+            runMode: task.runMode,
+            agentConfig: task.agentConfig,
+            requireOnline: true,
+          });
           await requireLimit(deps, {
             accountId: grant.accountId,
             workspaceId: grant.workspaceId,
@@ -3241,6 +3283,133 @@ function registerTaskNoteTools(
   );
 }
 
+function registerWorkClaimTools(
+  server: McpServer,
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  sessionId: string,
+  json: JsonResult,
+): void {
+  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: z4.string().uuid(),
+        expectedRevision: z4.number().int().min(0),
+        subjectNamespace: z4.string().min(1).max(WORK_CLAIM_NAMESPACE_MAX_BYTES),
+        subjectType: z4.enum([
+          "repository",
+          "branch",
+          "pull_request",
+          "issue",
+          "artifact",
+          "release",
+          "ci_run",
+          "other",
+        ]),
+        canonicalKey: z4.string().min(1).max(WORK_CLAIM_CANONICAL_KEY_MAX_BYTES),
+        displayLabel: z4.string().min(1).max(WORK_CLAIM_DISPLAY_LABEL_MAX_BYTES).optional(),
+        role: z4.enum(["working", "reviewing", "monitoring", "delivering"]),
+        versionKind: z4
+          .enum([
+            "git_commit",
+            "branch_head",
+            "pull_request_head",
+            "artifact_version",
+            "release_version",
+            "ci_run",
+            "other",
+          ])
+          .optional(),
+        versionValue: z4.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 === undefined) !== (versionValue === undefined)) {
+        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 === undefined ? {} : { 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: z4.string().uuid(),
+        claimId: z4.string().uuid(),
+        expectedRevision: z4.number().int().min(1),
+        reason: z4.enum([
+          "completed",
+          "cancelled",
+          "failed",
+          "superseded",
+          "no_longer_active",
+          "corrected",
+          "external_state_changed",
+          "other",
+        ]),
+      },
+    },
+    async ({ operationId, claimId, expectedRevision, reason }) => {
+      await authorize();
+      return json(
+        await releaseWorkClaim(deps.db, {
+          ...attemptClaims(),
+          operationId,
+          claimId,
+          expectedRevision,
+          reason,
+        }),
+      );
+    },
+  );
+}
+
 function registerPreferenceRegistryTools(
   server: McpServer,
   deps: ApiRouteDeps,
@@ -3280,6 +3449,7 @@ function registerPreferenceRegistryTools(
 }
 
 const MemoryKindSchema = z4.enum(["preference", "semantic", "procedural", "decision", "episodic"]);
+const MemoryWriteKindSchema = z4.enum(["semantic", "decision", "episodic"]);
 
 function scheduledTaskReceipt(
   operation: string,
@@ -3371,6 +3541,11 @@ export function memorySlackPublicationActor(
   };
 }
 
+function memoryPreview(text: string): string {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  return normalized.length <= 120 ? normalized : `${normalized.slice(0, 119)}…`;
+}
+
 function registerMemoryTools(
   server: McpServer,
   deps: ApiRouteDeps,
@@ -3379,10 +3554,17 @@ function registerMemoryTools(
   json: JsonResult,
   promptMode: WorkspaceMemoryPromptMode,
 ): void {
+  const publicationInputSchema = z4.object({
+    importance: z4.enum(["major", "normal", "minor"]),
+    audience: z4.literal("workspace"),
+    slackMode: z4.enum(["auto", "review", "never"]),
+    shareSummary: z4.string().trim().min(1).max(4_096),
+  });
+
   server.registerTool(
     "memory_search",
     {
-      description: `${MEMORY_SEARCH_TOOL_DESCRIPTION} Legacy preference-kind records are excluded from this tool because structured preferences are the only behavioral authority. To save something the user explicitly asked to keep, use \`remember\`; for your own findings use task notes and their promotion tools.`,
+      description: `${MEMORY_SEARCH_TOOL_DESCRIPTION} All existing Memory kinds are searchable. Legacy preference and procedure records are historical context, not active instructions; Skills and workspace instructions remain the behavioral authorities. When workspace Memory is enabled, use memory_save autonomously for durable facts, decisions, incidents, fixes, and outcomes, and memory_correct when an existing record is wrong or outdated.`,
       inputSchema: {
         query: z4.string().min(1),
         kind: MemoryKindSchema.optional(),
@@ -3405,10 +3587,239 @@ function registerMemoryTools(
       }),
   );
 
-  // Memory V1 writes are retired. Explicit user-directed knowledge goes
-  // through `remember`; an agent's own findings go through task notes and
-  // governed promotion. `memory_search` stays: reading the existing record
-  // set is still how an agent recalls what a workspace already knows.
+  // Memory writes are agent-only. Human creation and curation use the REST/UI
+  // surface; a non-attempt MCP principal may search but cannot mutate Memory.
+  if (exactAgentAttemptClaims(grant) === null) return;
+
+  server.registerTool(
+    "memory_save",
+    {
+      description: MEMORY_SAVE_TOOL_DESCRIPTION,
+      inputSchema: {
+        text: z4.string().min(1),
+        kind: MemoryWriteKindSchema,
+        confidence: z4.number().min(0).max(1).optional(),
+        replaces_id: z4.string().min(1).optional(),
+        slack_publication: publicationInputSchema.optional(),
+      },
+    },
+    async ({ text, kind, confidence, replaces_id, slack_publication }) => {
+      const actor = await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
+      const result = await saveWorkspaceMemoryWithSlackPublication(
+        deps.db,
+        {
+          accountId: grant.accountId,
+          workspaceId: grant.workspaceId,
+          sessionId,
+          text,
+          kind,
+          ...(confidence !== undefined ? { confidence } : {}),
+          ...(replaces_id ? { replacesId: replaces_id } : {}),
+          origin: "agent",
+        },
+        slack_publication
+          ? {
+              distribution: MemorySlackPublicationDistribution.parse(slack_publication),
+              actor: memorySlackPublicationActor(actor, sessionId, grant.subjectLabel ?? null)
+                .actor,
+              ownerLabel: actor.initiator.label ?? grant.subjectLabel ?? null,
+            }
+          : null,
+        deps.getDocumentServices().embedder,
+      );
+      let timelineWarning: string | null = null;
+      try {
+        await appendAndPublishEvents(deps.db, deps.bus, grant.workspaceId, sessionId, [
+          {
+            type: "memory.saved",
+            payload: {
+              memoryId: result.memory.id,
+              kind: result.memory.kind,
+              preview: memoryPreview(result.memory.text),
+              deduped: result.deduped,
+              ...(result.superseded ? { supersededMemoryId: result.superseded.id } : {}),
+            },
+          },
+        ]);
+      } catch {
+        timelineWarning = "Memory committed, but its session timeline event could not be recorded.";
+        console.warn("workspace memory save: committed without session timeline event", {
+          errorClass: "MemoryTimelineOperationError",
+          errorCode: "memory_save_timeline_append_failed",
+          origin: "api",
+          workspaceId: grant.workspaceId,
+          sessionId,
+          memoryId: result.memory.id,
+        });
+      }
+      const changed = !result.deduped || result.updated || result.superseded !== null;
+      const outcome =
+        result.updated || result.superseded !== null
+          ? "updated"
+          : result.deduped
+            ? "unchanged"
+            : "created";
+      return json(
+        mcpMutationReceipt({
+          operation: "memory_save",
+          committed: true,
+          outcome,
+          changed,
+          resource: {
+            type: "knowledge_memory",
+            id: result.memory.id,
+            state: result.memory.status,
+          },
+          relatedResources: result.superseded
+            ? [
+                {
+                  type: "knowledge_memory",
+                  id: result.superseded.id,
+                  state: result.superseded.status,
+                },
+              ]
+            : undefined,
+          timestamp: result.memory.updatedAt,
+          idempotency: { status: "not_supported" },
+          warnings: [
+            ...(!result.embedded
+              ? ["Memory committed without a vector embedding; keyword search remains available."]
+              : []),
+            ...(timelineWarning ? [timelineWarning] : []),
+          ],
+          facts: {
+            deduped: result.deduped,
+            dedupeReason: result.dedupeReason,
+            updatedInPlace: result.updated,
+            embedded: result.embedded,
+            slackPublicationDecision: result.slackPublication.decision?.eligible
+              ? "eligible"
+              : (result.slackPublication.decision?.reason ?? "not_requested"),
+            slackPublicationId:
+              result.slackPublication.enqueue?.kind === "enqueued" ||
+              result.slackPublication.enqueue?.kind === "replayed"
+                ? result.slackPublication.enqueue.publication.id
+                : null,
+            slackPublicationState:
+              result.slackPublication.enqueue?.kind === "enqueued" ||
+              result.slackPublication.enqueue?.kind === "replayed"
+                ? result.slackPublication.enqueue.publication.state
+                : null,
+          },
+        }),
+      );
+    },
+  );
+
+  server.registerTool(
+    "memory_correct",
+    {
+      description: MEMORY_CORRECT_TOOL_DESCRIPTION,
+      inputSchema: {
+        id: z4.string().min(1),
+        reason: z4.string().min(1).optional(),
+        replacement_text: z4.string().min(1).optional(),
+        slack_publication: publicationInputSchema.optional(),
+      },
+    },
+    async ({ id, reason, replacement_text, slack_publication }) => {
+      const actor = await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
+      const result = await correctWorkspaceMemoryWithSlackPublication(
+        deps.db,
+        {
+          accountId: grant.accountId,
+          workspaceId: grant.workspaceId,
+          sessionId,
+          id,
+          ...(reason ? { reason } : {}),
+          ...(replacement_text ? { replacementText: replacement_text } : {}),
+          origin: "agent",
+        },
+        slack_publication
+          ? {
+              distribution: MemorySlackPublicationDistribution.parse(slack_publication),
+              actor: memorySlackPublicationActor(actor, sessionId, grant.subjectLabel ?? null)
+                .actor,
+              ownerLabel: actor.initiator.label ?? grant.subjectLabel ?? null,
+            }
+          : null,
+        deps.getDocumentServices().embedder,
+      );
+      let timelineWarning: string | null = null;
+      try {
+        await appendAndPublishEvents(deps.db, deps.bus, grant.workspaceId, sessionId, [
+          {
+            type: "memory.corrected",
+            payload: {
+              memoryId: result.memory.id,
+              kind: result.memory.kind,
+              preview: memoryPreview(result.memory.text),
+              action: result.action,
+              ...(reason ? { reason: memoryPreview(reason) } : {}),
+              ...(result.replacement
+                ? {
+                    replacementMemoryId: result.replacement.id,
+                    replacementPreview: memoryPreview(result.replacement.text),
+                  }
+                : {}),
+            },
+          },
+        ]);
+      } catch {
+        timelineWarning =
+          "Memory correction committed, but its session timeline event could not be recorded.";
+        console.warn("workspace memory correction: committed without session timeline event", {
+          errorClass: "MemoryTimelineOperationError",
+          errorCode: "memory_correct_timeline_append_failed",
+          origin: "api",
+          workspaceId: grant.workspaceId,
+          sessionId,
+          memoryId: result.memory.id,
+        });
+      }
+      return json(
+        mcpMutationReceipt({
+          operation: "memory_correct",
+          committed: true,
+          outcome: "updated",
+          changed: true,
+          resource: {
+            type: "knowledge_memory",
+            id: result.memory.id,
+            state: result.memory.status,
+          },
+          relatedResources: result.replacement
+            ? [
+                {
+                  type: "knowledge_memory",
+                  id: result.replacement.id,
+                  state: result.replacement.status,
+                },
+              ]
+            : undefined,
+          timestamp: (result.replacement ?? result.memory).updatedAt,
+          idempotency: { status: "not_supported" },
+          warnings: timelineWarning ? [timelineWarning] : [],
+          facts: {
+            correctionAction: result.action,
+            slackPublicationDecision: result.slackPublication.decision?.eligible
+              ? "eligible"
+              : (result.slackPublication.decision?.reason ?? "not_requested"),
+            slackPublicationId:
+              result.slackPublication.enqueue?.kind === "enqueued" ||
+              result.slackPublication.enqueue?.kind === "replayed"
+                ? result.slackPublication.enqueue.publication.id
+                : null,
+            slackPublicationState:
+              result.slackPublication.enqueue?.kind === "enqueued" ||
+              result.slackPublication.enqueue?.kind === "replayed"
+                ? result.slackPublication.enqueue.publication.state
+                : null,
+          },
+        }),
+      );
+    },
+  );
 }
 
 // Fleet tools (M7 bring-your-own-compute). Session-scoped (they steer THIS
@@ -4003,46 +4414,145 @@ function registerWorkspaceOrchestrationTools(
     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: z4.number().int().positive().max(100).optional(),
           cursor: z4.string().max(512).optional(),
           includeLastMessage: z4.boolean().optional(),
-          orderBy: z4.enum(["createdAt", "updatedAt"]).optional(),
+          orderBy: z4.enum(["createdAt", "updatedAt", "relevance"]).optional(),
           updatedAfter: z4.string().max(64).optional(),
+          query: z4.string().max(MCP_DISCOVERY_QUERY_MAX_UTF16_CODE_UNITS).optional(),
+          statuses: z4
+            .array(
+              z4.enum([
+                "queued",
+                "running",
+                "idle",
+                "requires_action",
+                "recovering",
+                "waiting_capacity",
+                "failed",
+                "cancelled",
+              ]),
+            )
+            .max(8)
+            .optional(),
+          activeOnly: z4.boolean().optional(),
+          recentHours: z4.number().int().positive().max(WORK_DISCOVERY_RECENT_HOURS_MAX).optional(),
+          rootSessionId: z4.string().uuid().optional(),
+          parentSessionId: z4.string().uuid().nullable().optional(),
+          subject: z4
+            .object({
+              namespace: z4.string().min(1).max(WORK_CLAIM_NAMESPACE_MAX_BYTES),
+              type: WorkClaimSubjectType,
+              canonicalKey: z4.string().min(1).max(WORK_CLAIM_CANONICAL_KEY_MAX_BYTES),
+            })
+            .strict()
+            .optional(),
+          claimLimit: z4.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) : undefined;
-        const orderBy: SessionDiscoveryOrderBy =
-          requestedOrderBy ?? decodedCursor?.orderBy ?? "createdAt";
-        if (decodedCursor && decodedCursor.orderBy !== orderBy) {
-          throw new Error("sessions_list cursor order does not match orderBy");
-        }
-        const normalizedUpdatedAfter =
-          updatedAfter !== undefined
-            ? normalizeSessionDiscoveryRevision(updatedAfter, "updatedAfter")
-            : (decodedCursor?.updatedAfter ?? undefined);
-        if (normalizedUpdatedAfter !== undefined && 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: SessionDiscoveryOrderBy =
+            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 !== undefined
+              ? normalizeSessionDiscoveryRevision(updatedAfter, "updatedAfter")
+              : (decodedCursor?.updatedAfter ?? undefined);
+          if (normalizedUpdatedAfter !== undefined && 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: statuses as SessionStatus[] } : {}),
+            activeOnly: activeOnly === true,
+            ...(recentHours !== undefined ? { recentHours } : {}),
+            ...(rootSessionId ? { rootSessionId } : {}),
+            ...(parentSessionId !== undefined ? { parentSessionId } : {}),
+            ...(subject ? { subject: subject as WorkClaimSubjectFilter } : {}),
+            ...(claimLimit !== undefined ? { 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));
       },
     );
 
@@ -4199,7 +4709,7 @@ function registerWorkspaceOrchestrationTools(
     server.registerTool(
       "session_wait",
       {
-        description: `Block until a watched session has new durable events after your cursor, until your own session has pending machine input (a child result, an agent message, a steer), or until maxWaitSeconds (default ${SESSION_WAIT_DEFAULT_SECONDS}, max ${SESSION_WAIT_MAX_SECONDS}) elapses. Use this for short waits inside the current turn instead of sleeping and polling session_events/session_get/sessions_list while a child or peer session works; for long waits end this turn with goal_wait rather than looping session_wait for hours while holding the turn and sandbox. Pass each target's sessionId and afterSequence (its last seen sequence, 0 for a new session); returns immediately when anything already changed. Only turn lifecycle, agent.message.completed, blocking failures, goal facts, and session status/control changes count as a change; raw deltas, tool receipts, and sandbox diagnostics never wake it. Each changed target returns a bounded compact summary of up to ${SESSION_WAIT_EVENTS_PER_TARGET} exact durable events plus latestSequence (pass it back as the next afterSequence) and hasMore (drill down with session_events after=latestSequence). ownPendingUpdates > 0 means your own session has machine input that is delivered only when your next turn is claimed: finish this turn to receive it, or pass includeOwnPendingUpdates=false to keep waiting on the targets. timedOut=true means nothing changed; liveFanout=false means the live bus was unavailable and the wait relied on the deadline re-check. The whole result is byte-bounded: summaries are shortened first, then newest rows dropped, so a changed target may come back with events=[] and hasMore=true; read those rows with session_events after=latestSequence. The wait cannot exceed ${SESSION_WAIT_MAX_SECONDS} seconds because the MCP client request timeout is 60 seconds.`,
+        description: `Block until a watched session has new durable events after your cursor, until your own session has pending machine input (a child result, an agent message, a steer), or until maxWaitSeconds (default ${SESSION_WAIT_DEFAULT_SECONDS}, max ${SESSION_WAIT_MAX_SECONDS}) elapses. Use this for short waits inside the current turn instead of sleeping and polling session_events/session_get/sessions_list while a child or peer session works; for long waits end this turn with goal_wait rather than looping session_wait for hours while holding the turn and sandbox. Pass each target's sessionId and afterSequence (its last seen sequence, 0 for a new session). waitFor=change is the backward-compatible default and returns on turn lifecycle, agent.message.completed, blocking failures, goal facts, or session status/control changes. waitFor=completion is the child-result join: it ignores progress, completed commentary messages, goal facts, maintenance turns, and continuation segment settlements and returns only for a result-bearing final turn or a blocking state. A goal.completed event records goal state but is not a terminal child result. Raw deltas, tool receipts, sandbox diagnostics, and unrelated progress never wake either mode. Each changed target returns a bounded compact summary of up to ${SESSION_WAIT_EVENTS_PER_TARGET} exact durable events plus latestSequence (pass it back as the next afterSequence) and hasMore (drill down with session_events after=latestSequence). ownPendingUpdates > 0 means your own session has machine input that is delivered only when your next turn is claimed: finish this turn to receive it, or pass includeOwnPendingUpdates=false to keep waiting on the targets. timedOut=true means nothing changed; liveFanout=false means the live bus was unavailable and the wait relied on the deadline re-check. The whole result is byte-bounded: summaries are shortened first, then newest rows dropped, so a changed target may come back with events=[] and hasMore=true; read those rows with session_events after=latestSequence. The wait cannot exceed ${SESSION_WAIT_MAX_SECONDS} seconds because the MCP client request timeout is 60 seconds.`,
         inputSchema: {
           targets: z4
             .array(
@@ -4216,10 +4726,16 @@ function registerWorkspaceOrchestrationTools(
             .describe(
               "Also return when your own session has pending machine input (default true).",
             ),
+          waitFor: z4
+            .enum(["change", "completion"])
+            .optional()
+            .describe(
+              "change (default) returns on relevant activity; completion ignores messages, goal/progress, maintenance, and continuation segments until a result-bearing final turn or blocker.",
+            ),
           maxWaitSeconds: z4.number().int().min(1).max(SESSION_WAIT_MAX_SECONDS).optional(),
         },
       },
-      async ({ targets, includeOwnPendingUpdates, maxWaitSeconds }, extra) => {
+      async ({ targets, includeOwnPendingUpdates, waitFor, maxWaitSeconds }, extra) => {
         const distinct = new Set(targets.map((target) => target.sessionId));
         if (distinct.size !== targets.length) {
           throw new Error("session_wait targets must name distinct sessions");
@@ -4231,6 +4747,8 @@ function registerWorkspaceOrchestrationTools(
           await requireSession(deps.db, grant.workspaceId, target.sessionId);
         }
         const ownSessionId = includeOwnPendingUpdates === false ? null : callerSessionId;
+        const targetEventTypes =
+          waitFor === "completion" ? SESSION_WAIT_COMPLETION_EVENT_TYPES : SESSION_WAIT_EVENT_TYPES;
         // The API serves one transport per POST, so the worker's MCP cancel
         // notification never reaches this handler; the route binds the HTTP
         // request's abort to transport.close() (mcp/request-abort.ts), which
@@ -4247,6 +4765,9 @@ function registerWorkspaceOrchestrationTools(
             targets,
             ownSessionId,
             maxWaitMs: (maxWaitSeconds ?? SESSION_WAIT_DEFAULT_SECONDS) * 1_000,
+            targetEventTypes,
+            targetEventMatches:
+              waitFor === "completion" ? sessionWaitCompletionEventMatches : undefined,
             signal,
             source: {
               reauthorizeTargets: async (sessionIds) => {
@@ -4265,7 +4786,7 @@ function registerWorkspaceOrchestrationTools(
                   direction: "after",
                   limit: SESSION_WAIT_EVENTS_PER_TARGET,
                   payloadMode: "full",
-                  includeTypes: SESSION_WAIT_EVENT_TYPES,
+                  includeTypes: targetEventTypes,
                   maxBytes: SESSION_EVENT_MCP_MAX_BYTES * 4,
                 });
                 return { events: page.events, hasMore: page.hasMore };
@@ -4294,6 +4815,14 @@ function registerWorkspaceOrchestrationTools(
     const sessionCreateInput = z4
       .object({
         initialMessage: z4.string().min(1),
+        title: z4
+          .string()
+          .min(1)
+          .max(SESSION_TITLE_MAX_CHARACTERS)
+          .optional()
+          .describe(
+            "Concise semantic title for the child session. Omit only when the delegated goal or initial message already provides a suitable title; OpenGeni derives a sensitive-safe bounded fallback from that text.",
+          ),
         instructions: z4.string().min(1).max(SESSION_INSTRUCTIONS_MAX_CHARACTERS).optional(),
         goal: z4.unknown().optional(),
         resources: z4.array(z4.unknown()).optional(),
@@ -4376,7 +4905,7 @@ function registerWorkspaceOrchestrationTools(
       "session_create",
       {
         description:
-          "Spawn a new agent session (a worker). The child inherits this session's visibility; a private session can only create a same-owner private child. Give a goal-bearing child its delegated objective. Its goal.rootConstraints may be an exact applicable subset of this accepted turn's frozen root constraints; omit that field to inherit all of them. Omit sandbox for the safe default: compatible children share the creator's box, while a different Variable Set, Rig, or machineTarget gets its own box. Use 'new' for deliberate isolation or {groupId} for a strict compatible sibling join. Put targetSandboxId and its optional workingDir together inside machineTarget; a machineTarget is always an own-box create even when the parent is backend none. To create a non-delegating leaf, pass a narrowed firstPartyMcpTools list that omits session_create; do not use a child-local depth override. Public REST/SDK callers retain advanced absolute depth and explicit shared-placement controls.",
+          "Spawn a new agent session (a worker) only for a concrete, bounded subtask that can run independently and has a defined integration point in your current work. Do not delegate work you will also perform yourself; track the child and join its actual result before completing dependent work. Give the child a concise semantic title; if omitted, OpenGeni derives one from its delegated goal or initial message. The child inherits this session's visibility; a private session can only create a same-owner private child. Give a goal-bearing child its delegated objective. Its goal.rootConstraints may be an exact applicable subset of this accepted turn's frozen root constraints; omit that field to inherit all of them. Omit sandbox for the safe default: compatible children share the creator's box, while a different Variable Set, Rig, or machineTarget gets its own box. Use 'new' for deliberate isolation or {groupId} for a strict compatible sibling join. Put targetSandboxId and its optional workingDir together inside machineTarget; a machineTarget is always an own-box create even when the parent is backend none. To create a non-delegating leaf, pass a narrowed firstPartyMcpTools list that omits session_create; do not use a child-local depth override. Public REST/SDK callers retain advanced absolute depth and explicit shared-placement controls.",
         inputSchema: sessionCreateInput,
       },
       async (args) => {
@@ -4389,18 +4918,25 @@ function registerWorkspaceOrchestrationTools(
           if (callerSessionId !== null) {
             await authorizeFirstPartySession(deps, grant, callerSessionId, "session.child.create");
           }
-          const { machineTarget, ...request } = args;
-          const result = await createSessionForRequestWithOutcome(deps, grant, grant.workspaceId, {
-            ...request,
-            ...(machineTarget
-              ? {
-                  targetSandboxId: machineTarget.targetSandboxId,
-                  ...(machineTarget.workingDir !== undefined
-                    ? { workingDir: machineTarget.workingDir }
-                    : {}),
-                }
-              : {}),
-          });
+          const { machineTarget, title, ...request } = args;
+          const result = await createSessionForRequestWithOutcome(
+            deps,
+            grant,
+            grant.workspaceId,
+            {
+              ...request,
+              ...(machineTarget
+                ? {
+                    targetSandboxId: machineTarget.targetSandboxId,
+                    ...(machineTarget.workingDir !== undefined
+                      ? { workingDir: machineTarget.workingDir }
+                      : {}),
+                  }
+                : {}),
+            },
+            undefined,
+            title === undefined ? {} : { automaticTitleCandidate: title },
+          );
           return json(sessionCreateMutationReceipt(result, Boolean(request.idempotencyKey)));
         } catch (error) {
           return orchestrationFailureResult("session_create", error);
@@ -5470,10 +6006,12 @@ function boundedSessionDiscoveryLimit(limit: number | undefined): number {
 }
 
 export function encodeSessionDiscoveryCursor(cursor: SessionDiscoveryCursor): string {
+  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,
@@ -5523,6 +6061,8 @@ export function decodeSessionDiscoveryCursor(value: string): SessionDiscoveryCur
       snapshotAt?: unknown;
       snapshotRevision?: unknown;
       updatedAfter?: unknown;
+      sortRank?: unknown;
+      filterHash?: unknown;
     };
     if (
       parsed.v === undefined &&
@@ -5536,12 +6076,14 @@ export function decodeSessionDiscoveryCursor(value: string): SessionDiscoveryCur
       );
       return {
         orderBy: "createdAt",
+        sortRank: null,
         sortRevision: "0",
         sortAt: createdAt,
         id: parsed.id,
         snapshotAt: createdAt,
         snapshotRevision: "0",
         updatedAfter: null,
+        filterHash: null,
       };
     }
     // The timestamp-fenced v1 format was never safe for updated-order
@@ -5558,17 +6100,22 @@ export function decodeSessionDiscoveryCursor(value: string): SessionDiscoveryCur
     ) {
       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,
+        filterHash: null,
       };
     }
+    const isV2 = parsed.v === 2;
+    const isV3 = parsed.v === 3;
     if (
-      parsed.v !== 2 ||
-      (parsed.orderBy !== "createdAt" && parsed.orderBy !== "updatedAt") ||
+      (!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" ||
@@ -5579,6 +6126,18 @@ export function decodeSessionDiscoveryCursor(value: string): SessionDiscoveryCur
     ) {
       throw new Error("invalid cursor fields");
     }
+    if (
+      isV3 &&
+      (!Number.isSafeInteger(parsed.sortRank) ||
+        (parsed.sortRank as number) < 0 ||
+        typeof parsed.filterHash !== "string" ||
+        !/^[0-9a-f]{64}$/.test(parsed.filterHash))
+    ) {
+      throw new Error("invalid relevance cursor fields");
+    }
+    if (isV2 && (parsed.sortRank !== undefined || parsed.filterHash !== undefined)) {
+      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(
@@ -5599,14 +6158,19 @@ export function decodeSessionDiscoveryCursor(value: string): SessionDiscoveryCur
     if (parsed.orderBy === "createdAt" && (sortRevision !== "0" || snapshotRevision !== "0")) {
       throw new Error("creation cursor cannot carry activity revisions");
     }
+    const orderBy: SessionDiscoveryOrderBy = isV3
+      ? "relevance"
+      : (parsed.orderBy as "createdAt" | "updatedAt");
     return {
-      orderBy: parsed.orderBy,
+      orderBy,
+      sortRank: isV3 ? (parsed.sortRank as number) : null,
       sortRevision,
       sortAt,
       id: parsed.id,
       snapshotAt,
       snapshotRevision,
       updatedAfter: normalizedUpdatedAfter,
+      filterHash: isV3 ? (parsed.filterHash as string) : null,
     };
   } catch {
     throw new Error("sessions_list cursor is invalid");
@@ -5697,6 +6261,7 @@ export function capSessionDiscoveryPage(
         : null,
       queuedPromptCount: session.queuedPromptCount,
       children: session.treeStats,
+      relatedWork: session.workDiscovery,
       ...(includeLastMessage
         ? {
             latestMessage: session.latestMessage
@@ -5774,12 +6339,14 @@ export function capSessionDiscoveryPage(
       ? 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,
+            filterHash: page.filterHash,
           })
         : null
       : page.nextCursor