@opengeni/api-router 0.30.1 → 1.0.0

package/src/mcp/orchestration-failure-diagnostic.ts

@@ -0,0 +1,43 @@
+import type { ApiRouteDeps } from "@opengeni/core";
+import { failureDiagnostic, type FailureDiagnosticInput } from "@opengeni/observability";
+
+type OrchestrationTool = "session_create" | "session_send_message" | "session_steer";
+type CallerAttempt = {
+  sessionId: string;
+  turnId: string;
+  attemptId: string;
+  executionGeneration: number;
+};
+
+/** Caller identity comes only from the signed grant, never tool arguments. */
+export function orchestrationFailureDiagnostic(
+  deps: Pick<ApiRouteDeps, "settings" | "observability">,
+  tool: OrchestrationTool,
+  error: unknown,
+  caller: CallerAttempt | null,
+) {
+  const input: FailureDiagnosticInput = {
+    code: "mcp_orchestration_failed",
+    stage: `mcp.${tool}`,
+    retryDecision: "unknown",
+    error,
+    ...(caller ?? {}),
+  };
+  const diagnostic = failureDiagnostic(input, deps.settings.deploymentRevision);
+  let diagnosticExport: "disabled" | "queued" | "unavailable" = "disabled";
+  if (deps.settings.observabilityDiagnosticsEndpoint) {
+    diagnosticExport = "unavailable";
+    try {
+      const id = deps.observability?.recordFailureDiagnostic({
+        ...input,
+        diagnosticId: diagnostic.diagnosticId,
+      });
+      if (id === diagnostic.diagnosticId) diagnosticExport = "queued";
+    } catch {
+      // Evidence export cannot change the original error or replay the operation.
+    }
+  }
+  // Self-contained safe facts survive the ordinary failed-tool receipt even when
+  // the optional protected sink is disabled. Queued is not proof of delivery.
+  return { diagnostic, diagnosticExport };
+}

package/src/mcp/receipts.ts

@@ -26,6 +26,40 @@ export function mcpMutationReceipt(input: McpMutationReceiptInput): McpMutationR
   });
 }
 
+export function sessionControlMutationReceipt(input: {
+  operation: "session_pause" | "session_resume";
+  sessionId: string;
+  state: string;
+  receiptId: string;
+  timestamp: string;
+  outcome: "changed" | "unchanged" | "replayed";
+  interruptionCount: number;
+}): McpMutationReceiptType {
+  return mcpMutationReceipt({
+    operation: input.operation,
+    committed: true,
+    outcome:
+      input.outcome === "changed"
+        ? "updated"
+        : input.outcome === "unchanged"
+          ? "unchanged"
+          : "replayed",
+    changed: input.outcome === "changed",
+    resource: {
+      type: "session",
+      id: input.sessionId,
+      state: input.state,
+    },
+    relatedResources: [{ type: "session_command_receipt", id: input.receiptId }],
+    timestamp: input.timestamp,
+    idempotency: {
+      status: input.outcome === "replayed" ? "replayed" : "applied",
+    },
+    facts: { interruptionCount: input.interruptionCount },
+    nextAction: { tool: "session_get", arguments: { sessionId: input.sessionId } },
+  });
+}
+
 export type SessionCreateReceiptResult = {
   session: {
     id: string;

package/src/mcp/request-abort.ts

@@ -0,0 +1,44 @@
+import type { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+
+/**
+ * Serve one first-party MCP POST and bind the tool handlers' `extra.signal` to
+ * the HTTP client's connection.
+ *
+ * The API builds a fresh transport plus `McpServer` per POST, so an MCP
+ * `notifications/cancelled` from the worker would land on a different Protocol
+ * instance and never reach the handler. The only cancellation evidence this
+ * process can observe is the HTTP request's own abort (`Request.signal`, which
+ * Bun fires when the client disconnects). Closing the transport runs the SDK
+ * `Protocol._onclose`, which aborts every in-flight request handler's
+ * controller, so a blocking tool such as `session_wait` stops promptly when the
+ * worker drops the call (Steer, Pause, turn interruption).
+ *
+ * In JSON-response mode the SDK's `handleRequest` promise never settles once
+ * its stream mapping is cleared, so the race resolves a client-gone response
+ * instead of leaving the route handler pending.
+ */
+export async function handleMcpRequestWithClientAbort(
+  transport: Pick<WebStandardStreamableHTTPServerTransport, "handleRequest" | "close">,
+  request: Request,
+  clientSignal: AbortSignal | undefined,
+): Promise<Response> {
+  if (!clientSignal) return await transport.handleRequest(request);
+  const clientGone = () => new Response(null, { status: 499 });
+  if (clientSignal.aborted) {
+    await transport.close().catch(() => undefined);
+    return clientGone();
+  }
+  let onAbort: (() => void) | null = null;
+  const aborted = new Promise<Response>((resolve) => {
+    onAbort = () => {
+      void transport.close().catch(() => undefined);
+      resolve(clientGone());
+    };
+    clientSignal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    return await Promise.race([transport.handleRequest(request), aborted]);
+  } finally {
+    if (onAbort) clientSignal.removeEventListener("abort", onAbort);
+  }
+}

package/src/mcp/scheduled-task-input.ts

@@ -0,0 +1,76 @@
+import {
+  CreateScheduledTaskRequest,
+  ScheduledTaskAgentConfigInput,
+  ScheduledTaskRunMode,
+} from "@opengeni/contracts";
+import { z } from "zod/v4";
+
+/** The calling session is supplied by the signed grant, never by model text. */
+export function resolveScheduledTaskCreateInput(
+  input: Record<string, unknown>,
+  sessionId: string | null,
+) {
+  const runMode =
+    input.runMode ?? (input.targetSessionId || sessionId ? "existing_session" : undefined);
+  const targetSessionId =
+    input.targetSessionId ?? (runMode === "existing_session" ? sessionId : undefined);
+  if (!runMode)
+    throw new Error(
+      "Choose an existing chat or explicitly select reusable_session or new_session_per_run for a separate agent",
+    );
+  if (runMode === "existing_session" && !targetSessionId)
+    throw new Error("Choose the chat that should receive scheduled messages");
+  return CreateScheduledTaskRequest.parse({
+    ...input,
+    runMode,
+    ...(targetSessionId ? { targetSessionId } : {}),
+  });
+}
+
+export function scheduledTaskCreateToolInput() {
+  return z
+    .object({
+      ...CreateScheduledTaskRequest.options[1].out.shape,
+      runMode: ScheduledTaskRunMode.optional().describe(
+        "Omit to schedule a message in this chat. Choose reusable_session or new_session_per_run only when the user requests a separate agent.",
+      ),
+      targetSessionId: z
+        .string()
+        .uuid()
+        .optional()
+        .describe("Destination chat. Omitted existing-session destinations use the calling chat."),
+      prompt: ScheduledTaskAgentConfigInput.shape.prompt
+        .optional()
+        .describe(
+          "Message to send to an existing chat at each occurrence. The chat supplies its model, tools and machine.",
+        ),
+      agentConfig: z
+        .object(ScheduledTaskAgentConfigInput.shape)
+        .omit({ slackBotChannelId: true })
+        .strict()
+        .optional()
+        .describe(
+          "Creation settings for a separate scheduled agent. For an existing chat, supply prompt instead.",
+        ),
+    })
+    .omit({ agentLearning: true, connectionAuthorities: true })
+    .strict();
+}
+
+// Validate the original call, before projection defaults can add fields from
+// the separate-agent branch to the existing-chat message branch.
+export function scheduledTaskCreateToolValidation(sessionId: string | null) {
+  return z.record(z.string(), z.unknown()).superRefine((input, context) => {
+    try {
+      resolveScheduledTaskCreateInput(input, sessionId);
+    } catch (error) {
+      if (error instanceof z.ZodError)
+        for (const issue of error.issues) context.addIssue({ ...issue });
+      else
+        context.addIssue({
+          code: "custom",
+          message: error instanceof Error ? error.message : "Invalid schedule destination",
+        });
+    }
+  });
+}

package/src/mcp/scheduled-task-view.ts

@@ -301,6 +301,7 @@ function toolIdentity(
       kind: tool.kind,
       id: id.value,
       ...(tool.optional !== undefined ? { optional: tool.optional } : {}),
+      ...(tool.eager !== undefined ? { eager: tool.eager } : {}),
     },
     truncatedFieldCount: Number(id.truncated),
   };
@@ -308,6 +309,9 @@ function toolIdentity(
 
 export function scheduledTaskMcpSummary(task: ScheduledTask) {
   const action = task.action ?? ({ kind: "agent_turn" } as const);
+  const inheritsSessionSettings =
+    task.runMode === "existing_session" ||
+    (task.runMode === "reusable_session" && Boolean(task.reusableSessionId));
   const name = projectScheduledTaskUtf8(task.name, SCHEDULED_TASK_NAME_MAX_BYTES);
   const schedule = projectScheduledTaskSchedule(task.schedule);
   const model = task.agentConfig.model
@@ -318,6 +322,7 @@ export function scheduledTaskMcpSummary(task: ScheduledTask) {
   const result = {
     id: task.id,
     name: name.value,
+    executionDigest: task.executionDigest,
     status: task.status,
     schedule: schedule.schedule,
     runMode: task.runMode,
@@ -349,9 +354,10 @@ export function scheduledTaskMcpSummary(task: ScheduledTask) {
     createdAt: createdAt.value,
     updatedAt: updatedAt.value,
     configuration: {
-      model: model?.value ?? null,
-      reasoningEffort: task.agentConfig.reasoningEffort ?? null,
-      sandboxBackend: task.agentConfig.sandboxBackend ?? null,
+      source: inheritsSessionSettings ? "target_session" : "task_defaults",
+      model: inheritsSessionSettings ? null : (model?.value ?? null),
+      reasoningEffort: inheritsSessionSettings ? null : (task.agentConfig.reasoningEffort ?? null),
+      sandboxBackend: inheritsSessionSettings ? null : (task.agentConfig.sandboxBackend ?? null),
       hasGoal: task.agentConfig.goal !== undefined,
       promptBytes: Buffer.byteLength(task.agentConfig.prompt, "utf8"),
       resourceCount: task.agentConfig.resources.length,
@@ -380,6 +386,41 @@ export function scheduledTaskMcpSummary(task: ScheduledTask) {
   return result;
 }
 
+/** Exact bounded text; JSON escapes preserve even legacy lone UTF-16 units. */
+export function scheduledTaskPromptPage(
+  task: ScheduledTask,
+  offset: number,
+  expectedExecutionDigest?: string,
+) {
+  if (offset > 0 && !expectedExecutionDigest)
+    throw new Error("Continue with the executionDigest from the first prompt page");
+  if (expectedExecutionDigest !== undefined && expectedExecutionDigest !== task.executionDigest)
+    throw new Error("Scheduled task changed. Restart the prompt read at offset 0.");
+  const text = task.agentConfig.prompt;
+  if (!Number.isInteger(offset) || offset < 0 || offset > text.length)
+    throw new Error("Invalid prompt offset");
+  const splitsPair = (at: number) =>
+    at > 0 &&
+    at < text.length &&
+    /[\uD800-\uDBFF]/.test(text[at - 1]!) &&
+    /[\uDC00-\uDFFF]/.test(text[at]!);
+  if (splitsPair(offset))
+    throw new Error("Prompt offset splits a surrogate pair; use nextOffset from the previous page");
+  let end = Math.min(text.length, offset + 2048);
+  if (splitsPair(end)) end -= 1;
+  return {
+    id: task.id,
+    executionDigest: task.executionDigest,
+    prompt: {
+      text: text.slice(offset, end),
+      offset,
+      nextOffset: end < text.length ? end : null,
+      totalLength: text.length,
+      unit: "utf16" as const,
+    },
+  };
+}
+
 function buildScheduledTaskDetailMcp(
   task: ScheduledTask,
   budget: DetailBudget,