@opengeni/api-router 0.22.2 → 0.23.1

package/src/http/sse.ts

@@ -12,6 +12,11 @@ const SESSION_REPLAY_PAGE_SIZE = 100;
 const WORKSPACE_CONTROL_REPLAY_PAGE_SIZE = 100;
 export const SSE_QUEUED_FRAME_MAX_COUNT = 1;
 export const SSE_WRITE_STALL_TIMEOUT_MS = 30_000;
+export const SSE_HEARTBEAT_INTERVAL_MS = 15_000;
+const activeSseStreams: Record<"session" | "workspace_control", number> = {
+  session: 0,
+  workspace_control: 0,
+};
 
 export type SseDeliveryBoundObservation = {
   reason: "desired_size_non_positive" | "stall_timeout" | "frame_too_large";
@@ -251,6 +256,7 @@ export async function sseSessionStream(
   signal: AbortSignal,
   options: SessionSseDeliveryOptions = {},
 ): Promise<Response> {
+  const heartbeatIntervalMs = resolveHeartbeatInterval(options.heartbeatIntervalMs);
   if (
     options.reauthorize &&
     options.reauthorizeAfterMs !== undefined &&
@@ -266,13 +272,20 @@ export async function sseSessionStream(
   let unsubscribe: (() => void) | null = null;
   let delivery: LatestWinsDelivery<SessionEvent> | null = null;
   let reauthorizationTimer: ReturnType<typeof setTimeout> | null = null;
+  let heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
   let detachAbortListener = () => {};
+  let closeMetrics = () => {};
   const stopUpstream = () => {
+    closeMetrics();
     detachAbortListener();
     if (reauthorizationTimer) {
       clearTimeout(reauthorizationTimer);
       reauthorizationTimer = null;
     }
+    if (heartbeatTimer) {
+      clearTimeout(heartbeatTimer);
+      heartbeatTimer = null;
+    }
     delivery?.stop();
     const release = unsubscribe;
     unsubscribe = null;
@@ -284,6 +297,7 @@ export async function sseSessionStream(
     onObservation: sseObservationReporter("session", options),
     onStop: stopUpstream,
   });
+  closeMetrics = observeSseConnection("session", after, options.observability);
 
   const fail = (error: unknown) => {
     channel.fail(retryableSseFailure("session event stream delivery failed", error));
@@ -299,10 +313,24 @@ export async function sseSessionStream(
     }, interval);
   };
   scheduleReauthorization();
-  const writeFrame = async (frame: string) => {
-    if (!(await channel.write(frame))) {
-      throw new SseStreamStoppedError();
-    }
+  let writeTail = Promise.resolve();
+  const writeFrame = (frame: string): Promise<void> => {
+    const write = writeTail.then(async () => {
+      if (!(await channel.write(frame))) throw new SseStreamStoppedError();
+    });
+    writeTail = write.catch(() => {});
+    return write;
+  };
+  const scheduleHeartbeat = () => {
+    if (channel.stopped()) return;
+    heartbeatTimer = setTimeout(() => {
+      heartbeatTimer = null;
+      void writeFrame(": heartbeat\n\n")
+        .then(scheduleHeartbeat)
+        .catch((error) => {
+          if (!(error instanceof SseStreamStoppedError)) fail(error);
+        });
+    }, heartbeatIntervalMs);
   };
   const send = async (event: SessionEvent) => {
     if (event.sequence <= lastSent) return;
@@ -362,6 +390,7 @@ export async function sseSessionStream(
       SESSION_REPLAY_PAGE_SIZE,
     );
     await writeFrame(": connected\n\n");
+    scheduleHeartbeat();
     bootstrapping = false;
     const buffered = newestBuffered;
     newestBuffered = null;
@@ -425,14 +454,22 @@ export async function sseWorkspaceControlStream(
   signal: AbortSignal,
   options: SseDeliveryOptions = {},
 ): Promise<Response> {
+  const heartbeatIntervalMs = resolveHeartbeatInterval(options.heartbeatIntervalMs);
   let lastSent = after;
   let bootstrapping = true;
   let newestBuffered: WorkspaceControlEvent | null = null;
   let unsubscribe: (() => void) | null = null;
   let delivery: LatestWinsDelivery<WorkspaceControlEvent> | null = null;
+  let heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
   let detachAbortListener = () => {};
+  let closeMetrics = () => {};
   const stopUpstream = () => {
+    closeMetrics();
     detachAbortListener();
+    if (heartbeatTimer) {
+      clearTimeout(heartbeatTimer);
+      heartbeatTimer = null;
+    }
     delivery?.stop();
     const release = unsubscribe;
     unsubscribe = null;
@@ -444,12 +481,29 @@ export async function sseWorkspaceControlStream(
     onObservation: sseObservationReporter("workspace_control", options),
     onStop: stopUpstream,
   });
+  closeMetrics = observeSseConnection("workspace_control", after, options.observability);
 
   const fail = (error: unknown) => {
     channel.fail(retryableSseFailure("workspace control stream delivery failed", error));
   };
-  const writeFrame = async (frame: string) => {
-    if (!(await channel.write(frame))) throw new SseStreamStoppedError();
+  let writeTail = Promise.resolve();
+  const writeFrame = (frame: string): Promise<void> => {
+    const write = writeTail.then(async () => {
+      if (!(await channel.write(frame))) throw new SseStreamStoppedError();
+    });
+    writeTail = write.catch(() => {});
+    return write;
+  };
+  const scheduleHeartbeat = () => {
+    if (channel.stopped()) return;
+    heartbeatTimer = setTimeout(() => {
+      heartbeatTimer = null;
+      void writeFrame(": heartbeat\n\n")
+        .then(scheduleHeartbeat)
+        .catch((error) => {
+          if (!(error instanceof SseStreamStoppedError)) fail(error);
+        });
+    }, heartbeatIntervalMs);
   };
   const send = async (event: WorkspaceControlEvent) => {
     if (event.sequence <= lastSent) return;
@@ -505,6 +559,7 @@ export async function sseWorkspaceControlStream(
       WORKSPACE_CONTROL_REPLAY_PAGE_SIZE,
     );
     await writeFrame(": connected\n\n");
+    scheduleHeartbeat();
     bootstrapping = false;
     const buffered = newestBuffered;
     newestBuffered = null;
@@ -531,6 +586,37 @@ export async function sseWorkspaceControlStream(
   });
 }
 
+function observeSseConnection(
+  stream: "session" | "workspace_control",
+  after: number,
+  observability: Observability | undefined,
+): () => void {
+  activeSseStreams[stream] += 1;
+  observability?.incrementCounter({
+    name: "opengeni_sse_connections_total",
+    help: "SSE connections opened at the API boundary.",
+    labels: { stream, resume: after > 0 ? "resumed" : "fresh" },
+  });
+  observability?.setGauge?.({
+    name: "opengeni_sse_connections_active",
+    help: "Currently active SSE connections at the API boundary.",
+    labels: { stream },
+    value: activeSseStreams[stream],
+  });
+  let closed = false;
+  return () => {
+    if (closed) return;
+    closed = true;
+    activeSseStreams[stream] = Math.max(0, activeSseStreams[stream] - 1);
+    observability?.setGauge?.({
+      name: "opengeni_sse_connections_active",
+      help: "Currently active SSE connections at the API boundary.",
+      labels: { stream },
+      value: activeSseStreams[stream],
+    });
+  };
+}
+
 async function replayWorkspaceControlEvents(
   loadPage: (after: number, limit: number) => Promise<WorkspaceControlEvent[]>,
   send: (event: WorkspaceControlEvent) => Promise<void>,
@@ -561,6 +647,7 @@ class SseStreamStoppedError extends Error {}
 export type SseDeliveryOptions = {
   maxQueuedBytes?: number;
   stallTimeoutMs?: number;
+  heartbeatIntervalMs?: number;
   observability?: Observability | undefined;
   onObservation?: ((observation: SseDeliveryBoundObservation) => void) | undefined;
 };
@@ -597,3 +684,11 @@ function sseObservationReporter(
 function retryableSseFailure(message: string, error: unknown): TypeError {
   return error instanceof TypeError ? error : new TypeError(message, { cause: error });
 }
+
+function resolveHeartbeatInterval(value: number | undefined): number {
+  const interval = value ?? SSE_HEARTBEAT_INTERVAL_MS;
+  if (!Number.isSafeInteger(interval) || interval < 1_000 || interval > 60_000) {
+    throw new RangeError("SSE heartbeat interval must be between 1000 and 60000ms");
+  }
+  return interval;
+}

package/src/index.ts

@@ -366,11 +366,13 @@ export async function startApi() {
           { db: dbClient.db, settings, callout, observability },
           settings.natsUrl,
         );
-      } catch (error) {
+      } catch {
         // A responder start failure must not crash the API (other planes work); log
         // loudly — selfhosted agents will fail to connect until it is up.
         observability.error("OpenGeni NATS auth-callout responder failed to start", {
-          error: error instanceof Error ? error.message : String(error),
+          errorClass: "NatsAuthCalloutOperationError",
+          errorCode: "nats_auth_callout_start_failed",
+          origin: "api",
         });
       }
     } else {
@@ -422,7 +424,7 @@ export function shouldCreateScheduleAfterUpdateError(error: unknown): boolean {
 export function temporalScheduleSpec(schedule: ScheduledTaskScheduleSpec): ScheduleSpec {
   if (schedule.type === "interval") {
     return {
-      intervals: [{ every: `${schedule.everySeconds}s` }],
+      intervals: [temporalIntervalSpec(schedule)],
       ...(schedule.startAt ? { startAt: new Date(schedule.startAt) } : {}),
       ...(schedule.endAt ? { endAt: new Date(schedule.endAt) } : {}),
     };
@@ -456,6 +458,29 @@ export function temporalScheduleSpec(schedule: ScheduledTaskScheduleSpec): Sched
   };
 }
 
+function temporalIntervalSpec(
+  schedule: Extract<ScheduledTaskScheduleSpec, { type: "interval" }>,
+): NonNullable<ScheduleSpec["intervals"]>[number] {
+  const every = `${schedule.everySeconds}s` as `${number}s`;
+  if (!schedule.startAt) {
+    return { every };
+  }
+
+  // Temporal interval schedules match Epoch + (n * every) + offset. Its
+  // top-level startAt only filters matching times before that boundary, so it
+  // does not itself anchor the cadence. Derive the phase from startAt to make
+  // the stored OpenGeni timestamp the first interval boundary rather than the
+  // next epoch-aligned match.
+  const everyMilliseconds = BigInt(schedule.everySeconds) * 1_000n;
+  const startMilliseconds = BigInt(new Date(schedule.startAt).getTime());
+  const offsetMilliseconds =
+    ((startMilliseconds % everyMilliseconds) + everyMilliseconds) % everyMilliseconds;
+  return {
+    every,
+    ...(offsetMilliseconds === 0n ? {} : { offset: `${offsetMilliseconds}ms` as `${number}ms` }),
+  };
+}
+
 function temporalMonth(monthIndex: number) {
   return TEMPORAL_MONTHS[monthIndex]!;
 }

package/src/integrations/oauth-client.ts

@@ -282,8 +282,7 @@ export async function startMcpOAuth(
       error instanceof OAuthStartStageError
         ? error
         : new OAuthStartStageError("connection_lookup", oauthStartFailureReason(error), error);
-    const providerDomain = safeRequestedProviderDomain(context.payload);
-    logOAuthStartFailure(deps.observability, staged, providerDomain);
+    logOAuthStartFailure(deps.observability, staged);
     throw oauthStartApiError(staged);
   } finally {
     deadline.dispose();
@@ -1474,31 +1473,16 @@ function throwIfCallbackAborted(signal: AbortSignal, stage: OAuthCallbackStage):
 function logOAuthCallbackFailure(
   observability: Observability | undefined,
   error: OAuthCallbackStageError,
-  state: OAuthStatePayload | null,
+  _state: OAuthStatePayload | null,
 ): void {
-  observability?.error("MCP OAuth callback failed", {
-    "opengeni.oauth.stage": error.stage,
-    "opengeni.oauth.reason": error.reason,
-    "opengeni.oauth.provider_domain": state?.providerDomain,
-    "opengeni.oauth.resource_host": state ? safeHost(state.resource) : undefined,
-    "opengeni.oauth.authorization_server": state?.authorizationServer,
-    "opengeni.oauth.issuer": state?.issuer,
-    "opengeni.oauth.client_registration_method": state?.clientRegistrationMethod,
-    error: sanitizedError(error.cause),
-  });
+  observability?.error("MCP OAuth callback failed", oauthPublicErrorFields(error.cause));
 }
 
 function logOAuthStartFailure(
   observability: Observability | undefined,
   error: OAuthStartStageError,
-  providerDomain: string | undefined,
 ): void {
-  observability?.warn("MCP OAuth setup failed", {
-    "opengeni.oauth.stage": error.stage,
-    "opengeni.oauth.reason": error.reason,
-    "opengeni.oauth.provider_domain": providerDomain,
-    error: sanitizedError(error.cause),
-  });
+  observability?.warn("MCP OAuth setup failed", oauthPublicErrorFields(error.cause));
 }
 
 function oauthStartFailureReason(error: unknown): string {
@@ -1581,51 +1565,47 @@ function oauthStartStageLabel(stage: OAuthStartStage): string {
 function logOAuthVerificationWarning(
   observability: Observability | undefined,
   error: OAuthCallbackStageError,
-  state: OAuthStatePayload,
+  _state: OAuthStatePayload,
 ): void {
-  observability?.warn("MCP OAuth tools/list verification failed after token exchange", {
-    "opengeni.oauth.stage": error.stage,
-    "opengeni.oauth.reason": error.reason,
-    "opengeni.oauth.provider_domain": state.providerDomain,
-    "opengeni.oauth.resource_host": safeHost(state.resource),
-    "opengeni.oauth.mcp_host": safeHost(state.mcpUrl),
-    "opengeni.oauth.authorization_server": state.authorizationServer,
-    "opengeni.oauth.issuer": state.issuer,
-    "opengeni.oauth.client_registration_method": state.clientRegistrationMethod,
-    error: sanitizedError(error.cause),
-  });
-}
-
-function sanitizedError(error: unknown): string {
-  if (error instanceof HTTPException) {
-    return `HTTPException ${error.status}: ${error.message}`;
-  }
-  if (error instanceof Error) {
-    return `${error.name}: ${error.message}`;
-  }
-  return String(error);
+  observability?.warn(
+    "MCP OAuth tools/list verification failed after token exchange",
+    oauthPublicErrorFields(error.cause),
+  );
 }
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
+export type OAuthPublicErrorFields = {
+  errorClass: "OAuthOperationError";
+  errorCode: "oauth_operation_failed";
+  status?: number;
+  origin: "oauth";
+};
 
-function safeHost(rawUrl: string): string | undefined {
+/** Allowlisted projection for public telemetry; canonical OAuth errors stay exact. */
+export function oauthPublicErrorFields(error: unknown): OAuthPublicErrorFields {
+  const fields: OAuthPublicErrorFields = {
+    errorClass: "OAuthOperationError",
+    errorCode: "oauth_operation_failed",
+    origin: "oauth",
+  };
   try {
-    return new URL(rawUrl).host;
+    const rawStatus =
+      error instanceof HTTPException
+        ? error.status
+        : error && typeof error === "object"
+          ? ((error as { status?: unknown; statusCode?: unknown }).status ??
+            (error as { statusCode?: unknown }).statusCode)
+          : undefined;
+    const status = Number(rawStatus);
+    if (Number.isInteger(status) && status >= 100 && status <= 599) fields.status = status;
   } catch {
-    return undefined;
+    // Public telemetry is best-effort. A hostile getter/proxy must never
+    // replace the exact OAuth failure with a projection failure.
   }
+  return fields;
 }
 
-function safeRequestedProviderDomain(payload: OAuthStartRequest): string | undefined {
-  try {
-    const resource = payload.mcpUrl ?? payload.resource;
-    if (!resource) return undefined;
-    return canonicalProviderDomain(payload.providerDomain ?? new URL(resource).hostname);
-  } catch {
-    return undefined;
-  }
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
 }
 
 async function oauthErrorFromResponse(

package/src/integrations/slack-interactions.ts

@@ -120,6 +120,31 @@ export type NormalizedSlackInteraction = {
   text: string;
 };
 
+export function slackInteractionRoutePolicy(
+  entry: Pick<
+    SlackInteractionInboxEntry,
+    "triggerKind" | "slackChannelId" | "slackThreadTs" | "slackMessageTs" | "slackUserId"
+  >,
+) {
+  const directMessageShortcut = isDirectMessageShortcut(entry);
+  const source = slackRouteKey(entry.slackChannelId, entry.slackThreadTs ?? entry.slackMessageTs);
+  return {
+    directMessageShortcut,
+    requiresChannelAccess: !directMessageShortcut,
+    visibility:
+      entry.triggerKind === "dm" || directMessageShortcut
+        ? ("private" as const)
+        : ("workspace" as const),
+    // A human-to-human DM may be shared by multiple linked workspace users. The
+    // signed shortcut authorizes only the invoking user, so the pre-ack route
+    // must keep each user's private reservation distinct until it is rekeyed to
+    // that user's OpenGeni bot-DM thread.
+    initialRouteKey: directMessageShortcut
+      ? `${source}:shortcut-user:${entry.slackUserId}`
+      : source,
+  };
+}
+
 export function verifySlackRequestSignature(
   input: {
     timestamp: string | null;
@@ -566,7 +591,8 @@ async function processSlackInboxEntry(deps: ApiRouteDeps, entry: SlackInteractio
     await processSlackReactionInboxEntry(deps, entry);
     return;
   }
-  const routeKey = slackRouteKey(entry.slackChannelId, entry.slackThreadTs ?? entry.slackMessageTs);
+  const routePolicy = slackInteractionRoutePolicy(entry);
+  const routeKey = routePolicy.initialRouteKey;
   const existing = await getSlackInteractionByRoute(
     deps.db,
     entry.workspaceId,
@@ -588,7 +614,9 @@ async function processSlackInboxEntry(deps: ApiRouteDeps, entry: SlackInteractio
     subjectId: link?.subjectId ?? "service:slack-interaction",
     ...(existing?.sessionId ? { sessionId: existing.sessionId } : {}),
   });
-  await client.verifyChannelAccess(entry.slackChannelId);
+  if (routePolicy.requiresChannelAccess) {
+    await client.verifyChannelAccess(entry.slackChannelId);
+  }
   if (!link) {
     await client.postMessage({
       operationId: deterministicUuid(`slack-link:${entry.id}`),
@@ -604,6 +632,47 @@ async function processSlackInboxEntry(deps: ApiRouteDeps, entry: SlackInteractio
     throw new SlackInteractionPermanentError("identity_access_revoked");
   }
 
+  const alreadyDurable = await getSlackInteractionByClientEventId(
+    deps.db,
+    entry.workspaceId,
+    entry.connectionId,
+    `slack:${entry.providerEventId}`,
+  );
+  if (alreadyDurable) {
+    const { interaction, eventSessionId } = alreadyDurable;
+    if (interaction.visibility === "private" && interaction.owningSubjectId !== grant.subjectId) {
+      throw new SlackInteractionPermanentError("session_owner_mismatch");
+    }
+    if (interaction.sessionId !== null && interaction.sessionId !== eventSessionId) {
+      throw new SlackInteractionPermanentError("slack_interaction_event_conflict");
+    }
+    const boundInteraction =
+      interaction.sessionId !== null
+        ? interaction
+        : await bindSlackInteractionSession(deps.db, {
+            ...interaction,
+            owningSubjectId: grant.subjectId,
+            sessionId: eventSessionId,
+          });
+    if (!boundInteraction) {
+      throw new Error("Durable Slack interaction could not bind its reserved session");
+    }
+    const shouldRepairAcknowledgement =
+      interaction.triggeringProviderEventId === entry.providerEventId ||
+      (isDirectMessageShortcut(entry) && boundInteraction.ackSlackMessageTs === null);
+    if (shouldRepairAcknowledgement) {
+      const boundClient = await createOpenGeniSlackBotInteractionClient(deps, {
+        accountId: entry.accountId,
+        workspaceId: entry.workspaceId,
+        connectionId: entry.connectionId,
+        subjectId: grant.subjectId,
+        sessionId: eventSessionId,
+      });
+      await acknowledgeSlackSession(deps, boundClient, boundInteraction, entry);
+    }
+    return;
+  }
+
   if (existing?.sessionId) {
     await continueSlackSession(deps, grant, existing, entry);
     return;
@@ -621,7 +690,7 @@ async function processSlackInboxEntry(deps: ApiRouteDeps, entry: SlackInteractio
     routeKey,
     triggeringProviderEventId: entry.providerEventId,
     owningSubjectId: grant.subjectId,
-    visibility: entry.triggerKind === "dm" ? "private" : "workspace",
+    visibility: routePolicy.visibility,
   });
   if (interaction.sessionId) {
     await continueSlackSession(deps, grant, interaction, entry);
@@ -647,10 +716,14 @@ async function processSlackInboxEntry(deps: ApiRouteDeps, entry: SlackInteractio
     if (error instanceof HTTPException) {
       await client.postMessage({
         operationId: deterministicUuid(`slack-admission-failed:${interaction.id}`),
-        channelId: entry.slackChannelId,
-        ...(entry.triggerKind === "slash_command"
-          ? {}
-          : { threadTimestamp: entry.slackThreadTs ?? entry.slackMessageTs }),
+        ...(isDirectMessageShortcut(entry)
+          ? { userId: entry.slackUserId }
+          : {
+              channelId: entry.slackChannelId,
+              ...(entry.triggerKind === "slash_command"
+                ? {}
+                : { threadTimestamp: entry.slackThreadTs ?? entry.slackMessageTs }),
+            }),
         text: slackAdmissionFailureText(error),
       });
     }
@@ -662,21 +735,50 @@ async function processSlackInboxEntry(deps: ApiRouteDeps, entry: SlackInteractio
     sessionId: session.id,
   });
   if (!bound) throw new Error("Slack route could not bind its durable session");
+  const boundClient = await createOpenGeniSlackBotInteractionClient(deps, {
+    accountId: entry.accountId,
+    workspaceId: entry.workspaceId,
+    connectionId: entry.connectionId,
+    subjectId: grant.subjectId,
+    sessionId: session.id,
+  });
+  await acknowledgeSlackSession(deps, boundClient, bound, entry);
+}
+
+async function acknowledgeSlackSession(
+  deps: ApiRouteDeps,
+  client: OpenGeniSlackBotClient,
+  interaction: SlackInteraction,
+  entry: SlackInteractionInboxEntry,
+) {
+  if (!interaction.sessionId) {
+    throw new Error("Slack acknowledgement requires a bound session");
+  }
+  const directMessageShortcut = isDirectMessageShortcut(entry);
   const ack = await client.postMessage({
     operationId: deterministicUuid(`slack-ack:${interaction.id}`),
-    channelId: entry.slackChannelId,
-    ...(entry.triggerKind === "slash_command"
-      ? {}
-      : { threadTimestamp: entry.slackThreadTs ?? entry.slackMessageTs }),
-    text: `OpenGeni started this task. ${openSessionText(deps, entry.workspaceId, session.id)} Reply in this thread to continue, or reply \`stop\` to stop. Start a new top-level DM or invoke /opengeni again for a new session.`,
+    ...(directMessageShortcut
+      ? { userId: entry.slackUserId }
+      : {
+          channelId: entry.slackChannelId,
+          ...(entry.triggerKind === "slash_command"
+            ? {}
+            : { threadTimestamp: entry.slackThreadTs ?? entry.slackMessageTs }),
+        }),
+    text: directMessageShortcut
+      ? `OpenGeni started a private task from the selected DM message. ${openSessionText(deps, entry.workspaceId, interaction.sessionId)} Reply in this bot-DM thread to continue, or reply \`stop\` to stop. The source DM was not opened to the bot or made workspace-visible.`
+      : `OpenGeni started this task. ${openSessionText(deps, entry.workspaceId, interaction.sessionId)} Reply in this thread to continue, or reply \`stop\` to stop. Start a new top-level DM or invoke /opengeni again for a new session.`,
   });
-  if (entry.triggerKind === "slash_command") {
-    await rekeySlackInteractionRoute(deps.db, {
+  if (entry.triggerKind === "slash_command" || directMessageShortcut) {
+    const rekeyed = await rekeySlackInteractionRoute(deps.db, {
       ...interaction,
-      routeKey: slackRouteKey(entry.slackChannelId, ack.timestamp),
+      routeKey: slackRouteKey(ack.channelId, ack.timestamp),
+      slackChannelId: ack.channelId,
       slackThreadTs: ack.timestamp,
       ackSlackMessageTs: ack.timestamp,
+      repairUnacknowledgedPrivateShortcutDelivery: directMessageShortcut,
     });
+    if (!rekeyed) throw new Error("Slack acknowledgement could not rekey its durable route");
   }
 }
 
@@ -1407,6 +1509,12 @@ function slackRouteKey(channelId: string, threadTs: string) {
   return `${channelId}:${threadTs}`;
 }
 
+function isDirectMessageShortcut(
+  entry: Pick<SlackInteractionInboxEntry, "triggerKind" | "slackChannelId">,
+) {
+  return entry.triggerKind === "message_shortcut" && entry.slackChannelId.startsWith("D");
+}
+
 function deterministicUuid(value: string) {
   const bytes = createHash("sha256").update(value).digest().subarray(0, 16);
   bytes[6] = (bytes[6]! & 0x0f) | 0x50;

package/src/mcp/documents.ts

@@ -9,6 +9,7 @@ import {
 import { createKnowledgeMemory, listKnowledgeMemories, type Database } from "@opengeni/db";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod/v4";
+import { mcpMutationReceipt } from "./receipts";
 
 const SearchInputSchema = {
   query: z.string().min(1),
@@ -192,31 +193,47 @@ export function buildDocumentsMcpServer(
         metadata: z.record(z.string(), z.unknown()).optional(),
       },
     },
-    async ({ text, kind, scope, sourceRefs, confidence, metadata }) => ({
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(
-            await createKnowledgeMemory(db, {
-              accountId,
-              workspaceId,
-              status: "proposed",
-              kind: kind ?? "semantic",
-              scope: scope ?? "workspace",
-              text,
-              sourceRefs:
-                sourceRefs?.map((sourceRef) => ({
-                  ...sourceRef,
-                  metadata: sourceRef.metadata ?? {},
-                })) ?? [],
-              confidence: confidence ?? 0.5,
-              metadata: metadata ?? {},
-              createdBySessionId: options.createdBySessionId,
-            }),
-          ),
-        },
-      ],
-    }),
+    async ({ text, kind, scope, sourceRefs, confidence, metadata }) => {
+      const memory = await createKnowledgeMemory(db, {
+        accountId,
+        workspaceId,
+        status: "proposed",
+        kind: kind ?? "semantic",
+        scope: scope ?? "workspace",
+        text,
+        sourceRefs:
+          sourceRefs?.map((sourceRef) => ({
+            ...sourceRef,
+            metadata: sourceRef.metadata ?? {},
+          })) ?? [],
+        confidence: confidence ?? 0.5,
+        metadata: metadata ?? {},
+        createdBySessionId: options.createdBySessionId,
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              mcpMutationReceipt({
+                operation: "memory_propose",
+                committed: true,
+                outcome: "created",
+                changed: true,
+                resource: {
+                  type: "knowledge_memory",
+                  id: memory.id,
+                  state: memory.status,
+                },
+                timestamp: memory.updatedAt,
+                idempotency: { status: "not_supported" },
+                nextAction: { tool: "memory_search", arguments: {} },
+              }),
+            ),
+          },
+        ],
+      };
+    },
   );
 
   return server;