@opengeni/api-router 0.30.3 → 1.0.0

package/src/mcp/knowledge-entries.ts

@@ -0,0 +1,322 @@
+import {
+  AgentInstructionSaveRequest,
+  WORKSPACE_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
+  WorkspaceInstructionPolicyTarget,
+  KnowledgeEntryListRequest,
+  KnowledgeSavePreparationRequest,
+  KnowledgeEntrySaveRequest,
+  KnowledgeTaskNotePromotionRequest,
+  type AccessGrant,
+} from "@opengeni/contracts";
+import {
+  prepareKnowledgeFile,
+  prepareKnowledgeSave,
+  retainKnowledgeMessage,
+  searchKnowledgeEntries,
+  requireLiveAgentAttemptAuthorization,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  archiveKnowledgeEntry,
+  confirmLegacyKnowledge,
+  confirmLegacyInstruction,
+  getKnowledgeEntry,
+  listKnowledgeEntries,
+  nestedPostgresSqlState,
+  saveKnowledgeEntry,
+  saveAgentInstruction,
+  getAgentInstruction,
+  promoteTaskNoteToKnowledge,
+  withSessionRlsActorContext,
+  type KnowledgeContext,
+  KnowledgeEntryIdRequiredError,
+  KnowledgeEntryIdTakenError,
+} from "@opengeni/db";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+/** One structured write and retrieval path, independent of the legacy Memory toggle. */
+export function registerKnowledgeEntryTools(
+  server: McpServer,
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  sessionId: string,
+) {
+  if (grant.principalKind !== "agent_attempt") return;
+  async function run(
+    fn: (context: KnowledgeContext) => Promise<unknown>,
+    surface: "knowledge" | "instruction" = "knowledge",
+  ) {
+    try {
+      const attempt = await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
+      const context: KnowledgeContext = {
+        accountId: grant.accountId,
+        workspaceId: grant.workspaceId,
+        actor: {
+          kind: "agent",
+          sessionId: attempt.callerSessionId,
+          turnId: attempt.turnId,
+          attemptId: attempt.attemptId,
+          executionGeneration: attempt.executionGeneration,
+        },
+      };
+      const result = await withSessionRlsActorContext(
+        {
+          subjectId: attempt.subjectId,
+          initiatingHumanSubjectId: attempt.initiatingHumanSubjectId,
+        },
+        () => fn(context),
+      );
+      return { content: [{ type: "text" as const, text: JSON.stringify(result) }] };
+    } catch (error) {
+      if (
+        error instanceof KnowledgeEntryIdTakenError ||
+        error instanceof KnowledgeEntryIdRequiredError
+      ) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({ error: { code: error.code, message: error.message } }),
+            },
+          ],
+        };
+      }
+      const state = nestedPostgresSqlState(error);
+      const message =
+        surface === "instruction"
+          ? state === "40001"
+            ? "This instruction changed. Read its current content and baseline, then retry the same intended edit against that exact state."
+            : state === "23505"
+              ? "This instruction operation ID was already used with different input. Reuse it only for an exact retry."
+              : state === "42501"
+                ? "The instruction change is unavailable in this task's scope or Agent learning policy. Off disables authoring, not the task. Do not ask for approval to continue."
+                : state === "22023" || state === "23514"
+                  ? `Invalid instruction change. Read the current instruction, use append for a new rule, or edit with one localized exact oldText match to update or remove text. Agents cannot replace the complete instruction. Each supplied text and the resulting instruction must stay within ${WORKSPACE_INSTRUCTION_POLICY_CONTENT_MAX_CHARS} characters, the same limit as the human editor.`
+                  : "Workspace instructions are temporarily unavailable. Retry the same operation ID only if the prior change may have succeeded."
+          : state === "40001"
+            ? "This entry changed. Read its current revision and retry your correction with the current version."
+            : state === "23505"
+              ? "This operation ID was already used with different input. Reuse it only for an exact retry."
+              : state === "42501"
+                ? "The entry, reference, or write is unavailable in this task's scope and Agent learning policy. Off disables saving, not your task. Do not ask for an approval to continue."
+                : state === "22023" || state === "23514"
+                  ? "Invalid Knowledge entry or relationship. Check the referenced IDs and revision before retrying."
+                  : "Knowledge is temporarily unavailable. Your task can continue; retry the same operation ID if saving may have succeeded.";
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({ error: { code: state ?? "knowledge_unavailable", message } }),
+          },
+        ],
+      };
+    }
+  }
+  // Compatibility recovery for tool selections persisted before the cutover.
+  // This name is absent from new defaults. No legacy proposal writer is registered.
+  server.registerTool(
+    "remember_confirm",
+    {
+      description:
+        "Finish an existing pre-migration remember confirmation after its exact human answered Save. Knowledge publishes the migrated entry; instruction proposals retain their original authority. This tool never creates new proposals.",
+      inputSchema: {
+        operationId: z.uuid(),
+        claimId: z.uuid().optional(),
+        proposalId: z.uuid().optional(),
+        decisionReceiptId: z.uuid().optional(),
+        humanInputRequestId: z.uuid(),
+      },
+    },
+    (input) =>
+      run(async (context) => {
+        if (input.claimId && !input.proposalId && !input.decisionReceiptId) {
+          return confirmLegacyKnowledge(deps.db, context, {
+            operationId: input.operationId,
+            claimId: input.claimId,
+            humanInputRequestId: input.humanInputRequestId,
+          });
+        }
+        if (input.proposalId && input.decisionReceiptId && !input.claimId) {
+          return confirmLegacyInstruction(deps.db, context, {
+            operationId: input.operationId,
+            proposalId: input.proposalId,
+            decisionReceiptId: input.decisionReceiptId,
+            humanInputRequestId: input.humanInputRequestId,
+          });
+        }
+        throw new Error("Pass exactly one existing confirmation target");
+      }),
+  );
+  server.registerTool(
+    "knowledge_prepare_save",
+    {
+      description:
+        "Before saving useful lasting Knowledge, find related published entries and unapproved proposals, and fetch the full authorized collection map with descriptions and parent IDs in one read-only call. First choose the destination: future behavior belongs in instruction_policy_save for short always-on workspace rules or skill_save for applicable procedures and preferences, not Knowledge. Supply a concise subject and the proposed fact, decision, requirement or incident. Search spans all authorized collections. Reuse an existing entry when unchanged; read its current content before a correction, preserve evidence, or create only when distinct. Pending matches are unapproved. Choose collections from this map in your writable scope. A collection may have both published and pending versions. If collections.complete is false, continue with collectionCursors=collections.nextCursors; never mistake a partial catalog for the whole map. Long descriptions explicitly report truncation and can be read with knowledge_get. This call saves and approves nothing.",
+      inputSchema: KnowledgeSavePreparationRequest.shape,
+    },
+    (input) =>
+      run((context) =>
+        prepareKnowledgeSave(
+          deps.db,
+          context,
+          input,
+          () => deps.getDocumentServices().embedder,
+          undefined,
+          deps.settings,
+        ),
+      ),
+  );
+  server.registerTool(
+    "knowledge_search",
+    {
+      description:
+        "Find Knowledge from useful findings and explicitly retained reference sources. Supporting chat/file evidence is excluded from ordinary published discovery; set includeEvidence=true only when searching that evidence deliberately. Use a concise subject or entity name first (for example Acme); omit scope to search all authorized scopes. If a query returns no entries, retry the key name alone in the same scope or browse groups before concluding the information is absent. Default view=published is accepted knowledge. Also search view=needs_review before creating or updating entries, to reuse pending findings and collections from earlier tasks. Pending revisions are unapproved proposals, not accepted facts or instructions; preserve that status when discussing them. Reading a proposal never approves it. Personal tasks search the verified user's personal and authorized shared Knowledge; shared tasks search shared Knowledge.",
+      inputSchema: KnowledgeEntryListRequest.omit({
+        view: true,
+        sessionId: true,
+        reviewBatchId: true,
+        rootOnly: true,
+      }).extend({ view: z.enum(["published", "needs_review"]).default("published") }).shape,
+    },
+    (input) =>
+      run((context) =>
+        searchKnowledgeEntries(
+          deps.db,
+          context,
+          input,
+          () => deps.getDocumentServices().embedder,
+          deps.settings,
+        ),
+      ),
+  );
+  server.registerTool(
+    "knowledge_browse",
+    {
+      description:
+        "Browse Knowledge groups or the entries in a group. A group collects references to the same entries across sources and can contain nested groups. Pass its groupId to list direct members. Membership never grants access or duplicates content.",
+      inputSchema: {
+        groupId: z.uuid().optional(),
+        view: z.enum(["published", "needs_review"]).default("published"),
+        cursor: z.string().optional(),
+        limit: z.number().int().positive().max(50).optional(),
+      },
+    },
+    (input) =>
+      run((context) =>
+        listKnowledgeEntries(deps.db, context, {
+          ...input,
+          ...(input.groupId ? {} : { kind: "group" as const }),
+        }),
+      ),
+  );
+  server.registerTool(
+    "knowledge_get",
+    {
+      description:
+        "Read a Knowledge entry, its exact revision, evidence and collections. Default view=published reads accepted information. Use view=needs_review to inspect a pending proposal before improving it; revision.outcome=pending means unapproved. Pending information must not be presented as accepted or used to activate instructions. Source text is paginated. Use returned IDs and current version when citing, relating or correcting an entry.",
+      inputSchema: {
+        entryId: z.uuid(),
+        revisionId: z.uuid().optional(),
+        view: z.enum(["published", "needs_review"]).default("published"),
+        offset: z.number().int().nonnegative().default(0),
+        maxChars: z.number().int().positive().max(16_000).default(8_000),
+      },
+    },
+    (input) =>
+      run(async (context) => {
+        const record = await getKnowledgeEntry(deps.db, context, input.entryId, {
+          revisionId: input.revisionId,
+          view: input.view,
+        });
+        if (!record) return { found: false };
+        const content = record.revision.entry.content;
+        const end = Math.min(content.length, input.offset + input.maxChars);
+        return {
+          found: true,
+          ...record,
+          revision: {
+            ...record.revision,
+            entry: { ...record.revision.entry, content: content.slice(input.offset, end) },
+          },
+          contentRange: {
+            start: input.offset,
+            end,
+            total: content.length,
+            nextOffset: end < content.length ? end : null,
+          },
+        };
+      }),
+  );
+  server.registerTool(
+    "knowledge_retain_file",
+    {
+      description:
+        "Retain source text from an existing uploaded file only when it supports useful lasting Knowledge, or the user wants the file kept as a reusable reference. Ordinary chat attachments are not automatically added to Knowledge. Use purpose=evidence (default) for supporting material, or purpose=reference for a deliberately retained searchable reference. The original stays in Files. Read the image itself before drawing visual conclusions; OCR text is only evidence. Repeated calls reuse the same source and do not change its purpose, duplicate review requests or revive rejected/archived sources. To make previously retained evidence a searchable reference, read its current revision with knowledge_get and use knowledge_save to set source.purpose=reference while preserving content and links. Selected findings are optional separate knowledge_save entries with evidence pointing to the returned revision. A pending receipt never pauses the task.",
+      inputSchema: {
+        fileId: z.uuid(),
+        purpose: z.enum(["evidence", "reference"]).default("evidence"),
+      },
+    },
+    ({ fileId, purpose }) => run((context) => prepareKnowledgeFile(deps, context, fileId, purpose)),
+  );
+  server.registerTool(
+    "knowledge_retain_message",
+    {
+      description:
+        "Retain the exact text of a user message as supporting evidence only after identifying useful lasting Knowledge to save. Do not retain routine approvals, acknowledgments, task instructions or status chatter merely because they occurred. The source stays out of ordinary Knowledge discovery and can be read through its evidence link. Use when a user supplies or confirms a durable fact, before saving a finding based on it. Omit messageId for the user message that triggered this turn, or pass an earlier user message event ID from this same conversation. The server copies the actual message, preserves its identity and follows this task's learning policy. Repeated calls reuse the source. Cite the returned entryId/revisionId as evidence in knowledge_save, with location.messageIds=[messageId]. Retaining a message does not prove every statement in it or approve a pending finding.",
+      inputSchema: { messageId: z.uuid().optional() },
+    },
+    ({ messageId }) => run((context) => retainKnowledgeMessage(deps.db, context, messageId)),
+  );
+  server.registerTool(
+    "knowledge_save",
+    {
+      description:
+        "Retain retrieval-only facts, decisions, requirements, incidents or notes, or deliberately selected reference sources, not a behavioral preference or instruction for future sessions. Use instruction_policy_save for short always-on workspace rules and skill_save for applicable procedures and behavioral preferences; do not store them here as facts such as 'the user prefers concise replies', even if those destinations are unavailable or require review. First use knowledge_prepare_save when available (otherwise search published and needs_review Knowledge and browse collections). Skip unchanged duplicates; improve an existing entry when the subject is the same. Do not save routine approvals, acknowledgments, temporary instructions, screenshots or OCR merely because they occurred. State the reusable finding with enough context for a future task, preserve uncertainty and evidence, and place it in the relevant existing collections. Do this autonomously when useful for future work. Choose kind by content: source for retained original text; fact for a specific claim (the label is not verification); decision for a choice made and its reasoning; requirement for a need or constraint; incident for a problem with cause, fix and outcome when known; note for other useful context. Choose the closest kind without asking the user to classify it. A group is a collection about a customer, product, system or subject, not a finding type. Search published and needs_review views for an existing entry and relevant group before creating one, use groupIds to link entries across sources, and reuse an entry in multiple groups instead of copying it. Nest collections by setting a group entry's groupIds to its parent collections; keep the hierarchy shallow and useful, and never create circular membership. To create, omit entryId and pass expectedVersion 0; the returned entryId identifies the new entry. To correct or reorganize, pass an existing entryId and its current version. Source text and selected facts are independent entries, not mandatory duplicate stages. Evidence pins another entry's exact revision. When a user supplies or confirms a fact, retain the actual message with knowledge_retain_message and cite the returned revision; do not leave its provenance only in prose. Preserve existing evidence and relationships on corrections unless they are specifically no longer applicable; a contradictory original remains useful evidence of what changed. Use the same operationId only for an exact retry. Agent learning decides publication: published is available immediately; pending is saved for review and your task continues without an approval prompt. Do not turn Knowledge into instructions or Skills.",
+      inputSchema: KnowledgeEntrySaveRequest.omit({ scope: true }).shape,
+    },
+    (input) => run((context) => saveKnowledgeEntry(deps.db, context, input)),
+  );
+  server.registerTool(
+    "knowledge_archive",
+    {
+      description:
+        "Archive obsolete Knowledge while preserving its history. Prefer a correction when an entry still has useful information. Requires the current entry version and follows this task's Agent learning policy.",
+      inputSchema: {
+        operationId: z.uuid(),
+        entryId: z.uuid(),
+        expectedVersion: z.number().int().positive(),
+      },
+    },
+    (input) => run((context) => archiveKnowledgeEntry(deps.db, context, input)),
+  );
+  server.registerTool(
+    "instruction_policy_get",
+    {
+      description:
+        "Read the current standing instruction and exact baseline for one target before every change. Preserve unrelated rules exactly. Reading remains available when agent authoring is Off.",
+      inputSchema: { target: WorkspaceInstructionPolicyTarget },
+    },
+    (input) => run((context) => getAgentInstruction(deps.db, context, input.target), "instruction"),
+  );
+  server.registerTool(
+    "instruction_policy_save",
+    {
+      description: `Change a concise standing workspace instruction through this task's Agent learning policy. Use for short always-on behavior such as 'Keep replies concise; expand when asked', within the intended workspace scope; active instructions enter applicable prompts without Knowledge retrieval. Read the current policy first and submit its exact baseline. Use editMode=append by default for a new rule; it preserves the current content and adds one blank-line separator. Use edit with a localized oldText that occurs exactly once and newText to update or remove only that passage. Agents cannot replace the complete instruction; direct the user to the manual workspace-instruction editor for a whole-policy rewrite. Each supplied text and the resulting instruction are limited to ${WORKSPACE_INSTRUCTION_POLICY_CONTENT_MAX_CHARS} characters, the same limit as the human editor. Facts and incidents belong in knowledge_save and reusable procedures or context-specific preferences in skill_save. Preserve personal scope rather than creating a workspace-wide rule. Review first saves an inactive revision and returns pending; continue the task without an approval question. Report the actual receipt; Knowledge is not a workaround for Off, pending review, unavailable scope or size limits.`,
+      inputSchema: AgentInstructionSaveRequest.shape,
+    },
+    (input) => run((context) => saveAgentInstruction(deps.db, context, input), "instruction"),
+  );
+  server.registerTool(
+    "task_note_promote_knowledge",
+    {
+      description:
+        "Retain one active task note as durable Knowledge with its exact text and origin, only for retrieval-only information. Do not promote behavior rules or preferences to Knowledge; use instruction_policy_save for short always-on workspace rules or skill_save for applicable procedures and preferences, under their own scope and learning policy. Omit entryId; the returned entryId identifies the new entry. The note stays temporary and unchanged; this creates one Knowledge entry in this task's scope, governed by the same learning policy. Pending review never pauses the task. Use knowledge_save for a selected or rewritten finding instead.",
+      inputSchema: KnowledgeTaskNotePromotionRequest.shape,
+    },
+    (input) => run((context) => promoteTaskNoteToKnowledge(deps.db, context, input)),
+  );
+}

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,