@opengeni/api-router 2.10.0-canary.0 → 2.10.0-canary.2

package/src/mcp/server.ts

@@ -1,4 +1,9 @@
 import { createHash, randomUUID } from "node:crypto";
+import {
+  prepareWorkspaceArtifactUpload,
+  prepareWorkspaceArtifactPublication,
+  workspaceArtifactDownloads,
+} from "../site-uploads";
 import {
   CreateScheduledTaskRequest,
   boundSessionMcpText as capSessionDiscoveryText,
@@ -169,7 +174,7 @@ import {
   searchCapabilityCatalogItems,
   type ResolvedSessionAuthorization,
 } from "@opengeni/core";
-import { recordWorkspaceUsage, requireLimit } from "@opengeni/core";
+import { recordWorkspaceUsage, requireLimit, workflowIdForSession } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import {
   githubBindingStatus,
@@ -245,7 +250,15 @@ import {
   type FleetServices,
   type RunOnOp,
 } from "@opengeni/core";
-import { getSessionBackgroundCommand } from "@opengeni/db/session-background-commands";
+import {
+  readSessionBackgroundCommandOutput,
+  COMMAND_OUTPUT_MAX_BYTES,
+} from "@opengeni/db/session-background-commands";
+import {
+  readCommandWithWait,
+  COMMAND_READ_MAX_WAIT_SECONDS,
+  COMMAND_WAIT_DEFAULT_SECONDS,
+} from "./command-read";
 import {
   boundSessionEventCompactResult,
   boundSessionEventMcpPage,
@@ -293,10 +306,6 @@ import { registerRememberTools } from "./remember";
 import { mintSandboxCodemodeToken } from "@opengeni/runtime/sandbox";
 import { deleteScheduledTaskWithDurableCleanup } from "../scheduled-task-deletion";
 import { observeWorkDiscovery, summarizeWorkDiscoveryRows } from "../work-discovery-observability";
-import {
-  prepareWorkspaceArtifactContent,
-  readWorkspaceArtifactContent,
-} from "../workspace-artifact-content";
 
 export type McpServerOptions = {
   // Origin of the HTTP request that reached the MCP route. Browser-oriented
@@ -447,6 +456,7 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   wait_for_input: { sessionRequired: true, allOf: ["sessions:control"] },
   goal_complete: { sessionRequired: true, allOf: ["goals:manage"] },
   goal_pause: { sessionRequired: true, allOf: ["goals:manage"] },
+  goal_resume: { sessionRequired: true, allOf: ["goals:manage"] },
   memory_search: { sessionRequired: true, allOf: ["documents:search"] },
   memory_save: { sessionRequired: true, allOf: ["documents:search"] },
   memory_correct: { sessionRequired: true, allOf: ["documents:search"] },
@@ -519,6 +529,7 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   // self target, so the tool exists only for session-scoped grants.
   session_wait: { sessionRequired: true, allOf: ["sessions:read"] },
   command_wait: { sessionRequired: true, allOf: ["sessions:read"] },
+  command_read: { sessionRequired: true, allOf: ["sessions:read"] },
   session_create: { allOf: ["sessions:create"] },
   session_send_message: { allOf: ["sessions:control"] },
   session_pause: { allOf: ["sessions:control"] },
@@ -633,8 +644,9 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   atlassian_sources_list: { allOf: ["connections:read"] },
   atlassian_search: { allOf: ["connections:read"] },
   atlassian_get: { allOf: ["connections:read"] },
-  artifacts_list: { sessionRequired: true, allOf: ["artifacts:read"] },
+  artifacts_list: { allOf: ["artifacts:read"] },
   artifacts_get_source: { sessionRequired: true, allOf: ["artifacts:read"] },
+  artifacts_prepare_upload: { sessionRequired: true, allOf: ["artifacts:publish"] },
   artifacts_create: { sessionRequired: true, allOf: ["artifacts:publish"] },
   artifacts_publish: { sessionRequired: true, allOf: ["artifacts:publish"] },
   artifacts_rollback: { sessionRequired: true, allOf: ["artifacts:publish"] },
@@ -845,6 +857,24 @@ export function buildOpenGeniMcpServer(
       options.workspaceMemoryPromptMode ?? "retrieval_only",
     );
   }
+  server.registerTool(
+    "artifacts_list",
+    {
+      description:
+        "List the generic published artifacts in this workspace and their current versions.",
+      inputSchema: {},
+    },
+    async () => {
+      if (sessionId !== null && exactAgentAttemptClaims(grant) !== null) {
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.first_party_mcp.call");
+      }
+      return json(
+        redactWorkspaceArtifactListProvenance(
+          await listWorkspaceArtifacts(deps.db, grant.workspaceId),
+        ),
+      );
+    },
+  );
   if (sessionId !== null && exactAgentAttemptClaims(grant) !== null) {
     registerPreferenceRegistryTools(server, deps, grant, json);
     registerTaskNoteTools(server, deps, grant, sessionId, json);
@@ -2764,7 +2794,7 @@ function registerGoalTools(
     "wait_for_input",
     {
       description:
-        "End the current turn and wait out of turn for relevant session input. This is self-only and does not require a goal. Use it for long or uncertain waits instead of sleeping or repeatedly calling session_wait/command_wait. timeoutSeconds is a relative safety-wake duration; OpenGeni persists its absolute deadline, and timeout never cancels a background command. A human/API prompt, agent message or Steer, child terminal result, scheduled input, terminal background-command result, or the deadline wakes the session. Always end your turn immediately after the tool succeeds. Use goal_pause instead when the active goal itself should stop pending a human decision.",
+        "End the current turn and wait out of turn for relevant session input. This is self-only and does not require a goal. After success, the production runtime ends the turn at the tool-batch boundary without another model step or final message. Use it for long or uncertain waits instead of sleeping or repeatedly calling session_wait/command_wait. timeoutSeconds is a relative safety-wake duration; OpenGeni persists the first absolute deadline for the turn, and repeated calls do not extend it. Timeout never cancels a background command. A human/API prompt, agent message or Steer, child terminal result, scheduled input, terminal background-command result, or the deadline wakes the session. Use goal_pause instead when the active goal itself should stop pending a human decision.",
       inputSchema: {
         reason: inputWaitReasonSchema,
         timeoutSeconds: z4
@@ -2811,7 +2841,7 @@ function registerGoalTools(
         operationId,
         replay,
         nextAction:
-          "End your turn now. Relevant input or the timeout deadline will start a new turn; the timeout does not cancel commands.",
+          "The runtime yields this turn after the tool batch settles. Relevant input or the timeout deadline will start a new turn; the timeout does not cancel commands.",
       });
     },
   );
@@ -2917,6 +2947,61 @@ function registerGoalTools(
       );
     },
   );
+  server.registerTool(
+    "goal_resume",
+    {
+      description:
+        "Resume this session's paused goal regardless of who paused it or why. Already active is a successful no-op. Preserves the objective and resets continuation counters.",
+      inputSchema: {},
+    },
+    async () => {
+      await authorizeFirstPartySession(deps, grant, sessionId, "session.goal.write");
+      await requireSession(deps.db, grant.workspaceId, sessionId);
+      const existing = await getSessionGoal(deps.db, grant.workspaceId, sessionId);
+      if (!existing) {
+        throw new Error("this session has no goal; use goal_set first");
+      }
+      const { goal, events, workflowWakeRevision } = await setSessionGoalStatusWithEvent(
+        deps.db,
+        grant.workspaceId,
+        sessionId,
+        {
+          status: "active",
+          event: { type: "goal.resumed", actor: "agent" },
+        },
+      );
+      const changed = events.length > 0;
+      if (events.length > 0) {
+        await deps.bus.publish(grant.workspaceId, sessionId, events);
+      }
+      if (workflowWakeRevision !== null) {
+        await deps.workflowClient.wakeSessionWorkflow({
+          accountId: grant.accountId,
+          workspaceId: grant.workspaceId,
+          sessionId,
+          workflowId: workflowIdForSession(sessionId),
+          wakeRevision: workflowWakeRevision,
+        });
+      }
+      return json(
+        mcpMutationReceipt({
+          operation: "goal_resume",
+          committed: true,
+          outcome: changed ? "updated" : "unchanged",
+          changed,
+          resource: {
+            type: "session_goal",
+            id: goal.id,
+            version: goal.version,
+            state: goal.status,
+          },
+          timestamp: goal.updatedAt,
+          idempotency: { status: "not_supported" },
+          nextAction: { tool: "session_get", arguments: { sessionId } },
+        }),
+      );
+    },
+  );
 }
 
 type JsonResult = (value: unknown) => {
@@ -2961,13 +3046,15 @@ function registerWorkspaceArtifactTools(
   const mutation = async (response: WorkspaceArtifactMutationResponse) =>
     await projectWorkspaceArtifactMutationProvenance(response, canReadProvenanceSession);
   const prepare = (
-    html: string,
+    html: string | undefined,
     source?: { entrypoint: string; files: Array<{ path: string; content: string }> },
     requestedTools?: Array<{ serverId: string; toolName: string }>,
+    uploadId?: string,
   ) => {
     if (!deps.objectStorage) throw new Error("Object storage is not configured");
-    return prepareWorkspaceArtifactContent(deps.objectStorage, grant.workspaceId, {
-      html,
+    return prepareWorkspaceArtifactPublication(deps, grant, {
+      ...(html === undefined ? {} : { html }),
+      ...(uploadId ? { uploadId } : {}),
       ...(source ? { source } : {}),
       ...(requestedTools ? { requestedTools } : {}),
     });
@@ -2998,19 +3085,15 @@ function registerWorkspaceArtifactTools(
   };
 
   server.registerTool(
-    "artifacts_list",
+    "artifacts_prepare_upload",
     {
       description:
-        "List the generic published artifacts in this workspace and their current versions.",
+        "Get signed upload URLs for a Site's HTML and optional source JSON. Upload with curl or fetch, then pass uploadId to artifacts_create/artifacts_publish. No hashes or sizes needed. Source upload may be omitted for HTML-only Sites.",
       inputSchema: {},
     },
     async () => {
       await authorize();
-      return json(
-        redactWorkspaceArtifactListProvenance(
-          await listWorkspaceArtifacts(deps.db, grant.workspaceId),
-        ),
-      );
+      return json(await prepareWorkspaceArtifactUpload(deps, grant));
     },
   );
 
@@ -3018,7 +3101,7 @@ function registerWorkspaceArtifactTools(
     "artifacts_get_source",
     {
       description:
-        "Read an artifact's metadata and exact HTML source. Omit versionId for the current version.",
+        "Get artifact metadata, version id, and signed download URLs for HTML and optional source JSON. Download with curl or Bun. If source is null, edit the HTML instead. Omit versionId for the current version.",
       inputSchema: {
         artifactId: z4.string().uuid(),
         versionId: z4.string().uuid().optional(),
@@ -3043,11 +3126,11 @@ function registerWorkspaceArtifactTools(
         projectWorkspaceArtifactDetailProvenance(rawDetail, canReadSourceSession),
         projectWorkspaceArtifactVersionProvenance(ref.version, canReadSourceSession),
       ]);
-      const content = await readWorkspaceArtifactContent(deps.objectStorage, ref);
+      const downloads = await workspaceArtifactDownloads(deps.objectStorage, ref, "sandbox");
       return json({
         detail,
         version: projectedVersion,
-        ...content,
+        downloads,
       });
     },
   );
@@ -3065,7 +3148,8 @@ function registerWorkspaceArtifactTools(
           .regex(/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/)
           .max(96)
           .optional(),
-        html: z4.string().min(1).max(WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES),
+        html: z4.string().min(1).max(WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES).optional(),
+        uploadId: z4.string().uuid().optional(),
         source: z4
           .object({
             entrypoint: z4.string().min(1).max(256),
@@ -3092,7 +3176,16 @@ function registerWorkspaceArtifactTools(
         idempotencyKey: z4.string().min(1).max(200),
       },
     },
-    async ({ title, description, slug, html, source, requestedTools, idempotencyKey }) => {
+    async ({
+      title,
+      description,
+      slug,
+      html,
+      source,
+      requestedTools,
+      idempotencyKey,
+      uploadId,
+    }) => {
       await authorize();
       const artifactId = crypto.randomUUID();
       const slugBase = slug ?? (normalizeWorkspaceArtifactSlug(title) || "artifact");
@@ -3105,7 +3198,7 @@ function registerWorkspaceArtifactTools(
             requestedSlug: slug ?? null,
             title,
             description: description ?? null,
-            ...prepare(html, source, requestedTools),
+            ...(await prepare(html, source, requestedTools, uploadId)),
             ...provenance(idempotencyKey, "artifacts_create"),
           }),
         ),
@@ -3123,7 +3216,8 @@ function registerWorkspaceArtifactTools(
         expectedCurrentVersionId: z4.string().uuid(),
         title: z4.string().min(1).max(120).optional(),
         description: z4.string().max(2000).nullable().optional(),
-        html: z4.string().min(1).max(WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES),
+        html: z4.string().min(1).max(WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES).optional(),
+        uploadId: z4.string().uuid().optional(),
         source: z4
           .object({
             entrypoint: z4.string().min(1).max(256),
@@ -3156,6 +3250,7 @@ function registerWorkspaceArtifactTools(
       title,
       description,
       html,
+      uploadId,
       source,
       requestedTools,
       idempotencyKey,
@@ -3168,7 +3263,7 @@ function registerWorkspaceArtifactTools(
             expectedCurrentVersionId,
             ...(title !== undefined ? { title } : {}),
             ...(description !== undefined ? { description } : {}),
-            ...prepare(html, source, requestedTools),
+            ...(await prepare(html, source, requestedTools, uploadId)),
             ...provenance(idempotencyKey, "artifacts_publish"),
           }),
         ),
@@ -4747,13 +4842,25 @@ function registerWorkspaceOrchestrationTools(
       "session_get",
       {
         description:
-          "Get another session you are managing. Default detail=compact returns status, goal (including completion evidence or pause rationale), latest recorded goal progress, meaningful pause/wait state, queue counts, active turn and lastSequence for session_wait. Goal completion is not a terminal child result: join with session_wait waitFor=completion. Use detail=full for the legacy bounded configuration including resources, persisted tool refs, effectiveToolPolicy and variableSet ids (never variable values). Full mode is configuration, not a substitute for compact goal/progress facts. Do not use your own session id to reconstruct context; conversation history and persistent settings are supplied directly. Text loss is explicit; REST/UI defaults are unchanged.",
+          "Get an authorized session. Omit sessionId to read only the authenticated current agent session (a child reads itself, never its parent or root); sessionless/operator callers must provide an explicit ID. Both forms retain live-attempt and target authorization checks. Default detail=compact returns status, goal (including completion evidence or pause rationale), latest recorded goal progress, meaningful pause/wait state, queue counts, active turn and snapshot lastSequence. Goal completion is not a terminal child result: join with session_wait waitFor=completion from the last consumed event cursor (0 if none), not this snapshot lastSequence, which may already include an unread completion. For an already-settled child, retrieve its result-bearing completion with session_events or join from the last consumed cursor. Use detail=full for the legacy bounded configuration including resources, persisted tool refs, effectiveToolPolicy and variableSet ids (never variable values). Full mode is configuration, not a substitute for compact goal/progress facts. Self reads inspect session state, not conversation history, which is supplied directly. Text loss is explicit; REST/UI defaults are unchanged.",
         inputSchema: {
-          sessionId: z4.string().uuid(),
+          sessionId: z4
+            .string()
+            .uuid()
+            .optional()
+            .describe(
+              "Omit only to read the authenticated current agent session, never its parent or root. Sessionless callers must provide an explicit ID.",
+            ),
           detail: z4.enum(["compact", "full"]).optional(),
         },
       },
-      async ({ sessionId, detail }) => {
+      async ({ sessionId: requestedSessionId, detail }) => {
+        const sessionId = requestedSessionId ?? exactAgentAttemptClaims(grant)?.sessionId;
+        if (sessionId === undefined) {
+          throw new Error(
+            "session_get requires an explicit sessionId without authenticated current agent session context",
+          );
+        }
         const authorization = await authorizeFirstPartySession(
           deps,
           grant,
@@ -4793,9 +4900,14 @@ function registerWorkspaceOrchestrationTools(
       "session_events",
       {
         description:
-          "Read a compact semantic tail only when session_get status is insufficient. With no cursor, this returns the newest matching events and excludes raw message/reasoning/command/PTY deltas. Monitoring mode also omits a human/API user.message whose turn was never claimed (still queued, or deleted/edited/cancelled before any claim; waiting work is represented by sessions_list queuedPromptCount); the row appears at its own sequence once the turn is claimed. Use `latest` as an exclusive lookup for the authoritative newest durable sequence in exactly one semantic class; `receipt` is the concise alias for `tool_receipt`, and latest cannot be combined with type or class filters. Add `resultMode=compact` to latest for one bounded result-bearing completion/checkpoint/receipt without another inference. Use nextBefore to page older or explicit after/nextAfter to page forward. Type/class filters run in the RLS-scoped database query. payloadMode none|summary|full controls retained audit payload projection, but every model result is independently byte-capped with explicit truncation and exact covered sequence bounds. Exact retained forensic payloads, including unclaimed prompt rows, require mode=forensic or the access-controlled REST/SDK events API with mode=forensic&payloadMode=full; generic source bytes never retained by the audit boundary remain unavailable.",
+          "Read session history. Default view=conversation returns roughly ten complete user/assistant messages, including completed commentary, in a 16 KiB envelope; no token deltas or execution records. Prefer fewer complete messages; a single oversized message has fragment offsets and a lossless nextCursor continuation over retained source text, including large legacy rows. Fragment unit is codepoint for plain text or utf16 for codec text; pass the opaque v2 cursor unchanged (v1 cursors must restart). Pass cursor=nextCursor with sessionId, omitting other selectors; it binds the view, detail and direction. after/nextAfter and before/nextBefore only change position, never view or detail; use nextCursor when present to avoid skipping a message fragment. view=results returns final turn answers and actionable outcomes without duplicate message-completion text. view=tools returns compact call/result identities; includeArguments/includeOutput opt into one text or JSON-encoded value, and callId selects an exact call (sparse scans can return an empty advancing page). sourceExact=false and sourceOmitted identify oversized structured values that were omitted, never partial JSON presented as complete; scalar text remains resumable. Conversation/results/tools omit never-claimed human/API prompts and stale duplicate events. view=debug exposes the existing authorized audit query with explicit type/class filters, mode=monitoring|forensic and payloadMode=none|summary|full; raw deltas and never-claimed prompts require mode=forensic. Explicit legacy audit selectors remain supported without view. latest is an exclusive semantic-class lookup; resultMode=compact requires latest. No read observes commands or changes append-only history. REST behavior is unchanged.",
         inputSchema: {
           sessionId: z4.string().uuid(),
+          view: z4.enum(["conversation", "results", "tools", "debug"]).optional(),
+          cursor: z4.string().max(4096).optional(),
+          callId: z4.string().max(512).optional(),
+          includeArguments: z4.boolean().optional(),
+          includeOutput: z4.boolean().optional(),
           after: z4.number().int().nonnegative().optional(),
           before: z4.number().int().positive().optional(),
           limit: z4.number().int().positive().optional(),
@@ -4803,8 +4915,34 @@ function registerWorkspaceOrchestrationTools(
           mode: z4.enum(SessionEventReadMode.options).optional(),
           payloadMode: z4.enum(SessionEventPayloadMode.options).optional(),
           resultMode: z4.enum(SessionEventResultMode.options).optional(),
-          includeTypes: z4.array(z4.enum(SessionEventType.options)).max(100).optional(),
-          excludeTypes: z4.array(z4.enum(SessionEventType.options)).max(100).optional(),
+          includeTypes: z4
+            .array(
+              z4
+                .string()
+                .refine(
+                  (value) => SessionEventType.safeParse(value).success,
+                  "Unknown session event type",
+                ),
+            )
+            .max(100)
+            .describe(
+              "Debug audit event types, e.g. turn.completed, user.message, agent.message.completed, agent.toolCall.output. Validated against the canonical event-type registry.",
+            )
+            .optional(),
+          excludeTypes: z4
+            .array(
+              z4
+                .string()
+                .refine(
+                  (value) => SessionEventType.safeParse(value).success,
+                  "Unknown session event type",
+                ),
+            )
+            .max(100)
+            .describe(
+              "Debug audit event types to exclude; validated against the canonical event-type registry.",
+            )
+            .optional(),
           includeClasses: z4
             .array(z4.enum(SessionEventSemanticClass.options))
             .max(SessionEventSemanticClass.options.length)
@@ -4818,6 +4956,11 @@ function registerWorkspaceOrchestrationTools(
       },
       async ({
         sessionId,
+        view,
+        cursor,
+        callId,
+        includeArguments,
+        includeOutput,
         after,
         before,
         limit,
@@ -4825,19 +4968,75 @@ function registerWorkspaceOrchestrationTools(
         mode: requestedMode,
         payloadMode: requestedPayloadMode,
         resultMode: requestedResultMode,
-        includeTypes,
-        excludeTypes,
+        includeTypes: requestedIncludeTypes,
+        excludeTypes: requestedExcludeTypes,
         includeClasses,
         excludeClasses,
         latest,
       }) => {
         await authorizeFirstPartySession(deps, grant, sessionId, "session.events.read");
+        // Keep the model schema compact without weakening either MCP validation
+        // or direct adapter calls: the canonical registry owns accepted types.
+        const includeTypes = requestedIncludeTypes?.map((type) => SessionEventType.parse(type));
+        const excludeTypes = requestedExcludeTypes?.map((type) => SessionEventType.parse(type));
         const latestClass =
           latest === undefined ? undefined : sessionEventLatestClassToSemanticClass(latest);
         if (requestedResultMode === "compact" && latestClass === undefined) {
           throw new Error("resultMode=compact requires latest");
         }
         await requireSession(deps.db, grant.workspaceId, sessionId);
+        const auditRequested = [
+          requestedMode,
+          requestedPayloadMode,
+          requestedResultMode,
+          includeTypes,
+          excludeTypes,
+          includeClasses,
+          excludeClasses,
+          latest,
+        ].some((value) => value !== undefined);
+        if (((view !== undefined && view !== "debug") || cursor !== undefined) && auditRequested) {
+          throw new Error(
+            "Audit selectors require view=debug and cannot change a conversation cursor",
+          );
+        }
+        if (view !== "debug" && !auditRequested) {
+          const { readSessionEventView } = await import("./session-event-view");
+          const { listSessionEventSlices } = await import("@opengeni/db/session-event-slices");
+          return json(
+            await readSessionEventView(
+              {
+                sessionId,
+                view,
+                cursor,
+                callId,
+                includeArguments,
+                includeOutput,
+                after,
+                before,
+                direction: requestedDirection,
+                limit,
+              },
+              (options) =>
+                listSessionEventSlices(
+                  deps.db,
+                  grant.workspaceId,
+                  sessionId,
+                  options,
+                  (legacyOptions) =>
+                    listSessionEventPage(deps.db, grant.workspaceId, sessionId, legacyOptions),
+                ),
+            ),
+          );
+        }
+        if (
+          cursor !== undefined ||
+          callId !== undefined ||
+          includeArguments !== undefined ||
+          includeOutput !== undefined
+        ) {
+          throw new Error("cursor/callId/includeArguments/includeOutput require a non-debug view");
+        }
         if (
           latest &&
           [includeTypes, excludeTypes, includeClasses, excludeClasses].some(
@@ -4846,7 +5045,7 @@ function registerWorkspaceOrchestrationTools(
         ) {
           throw new Error("latest cannot be combined with event filters");
         }
-        const mode = requestedMode ?? (after !== undefined ? "forensic" : "monitoring");
+        const mode = requestedMode ?? "monitoring";
         const direction = latestClass
           ? "before"
           : (requestedDirection ??
@@ -4905,7 +5104,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 a background-command result), or until maxWaitSeconds (default ${SESSION_WAIT_DEFAULT_SECONDS}, max ${SESSION_WAIT_MAX_SECONDS}) elapses. Use this for one short wait inside the current turn instead of sleeping and polling session_events/session_get/sessions_list while a child or peer session works. Do not immediately repeat it after timedOut=true unless new evidence suggests completion within one more window; for long or uncertain waits call wait_for_input once and end the turn. Pass each target's sessionId and afterSequence (its last seen sequence, 0 for a new session). waitFor=change is the default and returns on turn lifecycle, agent.message.completed, terminal background commands, blocking failures, goal facts, or session status/control changes. waitFor=completion is the child-result join: it ignores progress, completed commentary messages, goal facts, background commands, 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.`,
+        description: `Wait once for durable session changes, your pending machine input, or maxWaitSeconds (default ${SESSION_WAIT_DEFAULT_SECONDS}, max ${SESSION_WAIT_MAX_SECONDS}). Pass targets with sessionId and afterSequence: the last consumed cursor, or 0. Never substitute session_get.lastSequence, which may include an unread completion. waitFor=change returns on turn lifecycle, completed messages, terminal commands, blockers, goal facts, or session control. waitFor=completion joins a child result: only a result-bearing final turn or blocker qualifies, not commentary, goal.completed, background commands, maintenance turns, or continuation segments. Neither mode wakes on raw deltas or tool receipts. Each target contains up to ${SESSION_WAIT_EVENTS_PER_TARGET} bounded summaries, latestSequence (the next afterSequence), and hasMore. For omitted rows use session_events view=results after=latestSequence for final outcomes, or view=debug with explicit filters for diagnostics; the default conversation view does not contain execution records. Byte limits can leave events=[] with hasMore=true. ownPendingUpdates > 0 means input will arrive when your next turn is claimed: finish this turn, or use includeOwnPendingUpdates=false to keep waiting. timedOut=true means no matching change; liveFanout=false means the deadline re-check supplied durable truth without the live bus. Do not immediately repeat a timeout without new evidence. For long or uncertain waits call wait_for_input once and end the turn.`,
         inputSchema: {
           targets: z4
             .array(
@@ -5007,124 +5206,53 @@ function registerWorkspaceOrchestrationTools(
     );
 
     if (callerSessionId !== null) {
-      server.registerTool(
-        "command_wait",
-        {
-          description: `Wait briefly for one background command owned by this session to settle, without provider-specific polling or write_stdin loops. The durable command row is authoritative. This returns immediately when the command is already terminal or otherwise waits up to maxWaitSeconds (default ${SESSION_WAIT_DEFAULT_SECONDS}, max ${SESSION_WAIT_MAX_SECONDS}) for its session.command.finished event or other pending input for this session. timedOut=true never cancels the command. Do not immediately repeat command_wait after a timeout unless new evidence suggests completion within one more window; for long or uncertain work call wait_for_input once and end the turn.`,
-          inputSchema: {
-            commandId: z4.string().uuid(),
-            maxWaitSeconds: z4.number().int().min(1).max(SESSION_WAIT_MAX_SECONDS).optional(),
+      for (const toolName of ["command_read", "command_wait"] as const) {
+        server.registerTool(
+          toolName,
+          {
+            description: `${toolName === "command_read" ? "Read retained output immediately, or briefly wait" : "Briefly wait using the same read operation as command_read"} for one command owned by the current session, across sandbox and Connected Machine providers. Returns bounded stdout/stderr chunks, durable state and exitCode, nextCursor and hasMore, plus explicit retention limitations. Pass nextCursor to continue; output remains readable after the process exits. A terminal read observes completion and suppresses only its still-pending inbox notification; running reads and already claimed history are unchanged. waitSeconds is at most 50; command_wait defaults to 45, command_read to 0. For long waits use wait_for_input. Neither tool sends stdin or cancels the command.`,
+            inputSchema: {
+              commandId: z4.string().uuid(),
+              cursor: z4.string().max(128).optional(),
+              waitSeconds: z4.number().int().min(0).max(COMMAND_READ_MAX_WAIT_SECONDS).optional(),
+              maxOutputBytes: z4.number().int().min(4).max(COMMAND_OUTPUT_MAX_BYTES).optional(),
+            },
           },
-        },
-        async ({ commandId, maxWaitSeconds }, extra) => {
-          await authorizeFirstPartySession(deps, grant, callerSessionId, "session.events.read");
-          const initialSession = await requireSession(deps.db, grant.workspaceId, callerSessionId);
-          let command = await getSessionBackgroundCommand(deps.db, {
-            accountId: grant.accountId,
-            workspaceId: grant.workspaceId,
-            sessionId: callerSessionId,
-            commandId,
-          });
-          if (!command) throw new Error("Background command not found in this session");
-
-          const terminal = () => command?.state === "exited" || command?.state === "lost";
-          let waitResult: Awaited<ReturnType<typeof waitForSessionChanges>> | null = null;
-          if (!terminal()) {
-            waitResult = await waitForSessionChanges({
-              targets: [{ sessionId: callerSessionId, afterSequence: initialSession.lastSequence }],
-              ownSessionId: callerSessionId,
-              maxWaitMs: (maxWaitSeconds ?? SESSION_WAIT_DEFAULT_SECONDS) * 1_000,
-              targetEventTypes: ["session.command.finished"],
-              targetEventMatches: (event) => {
-                const payload = event.payload;
-                return (
-                  payload !== null &&
-                  typeof payload === "object" &&
-                  !Array.isArray(payload) &&
-                  (payload as Record<string, unknown>).commandId === commandId
-                );
-              },
-              signal: extra?.signal,
-              source: {
-                readTargetEvents: async (target) => {
-                  const page = await listSessionEventPage(
-                    deps.db,
-                    grant.workspaceId,
-                    target.sessionId,
-                    {
-                      after: target.afterSequence,
-                      direction: "after",
-                      limit: SESSION_WAIT_EVENTS_PER_TARGET,
-                      payloadMode: "full",
-                      includeTypes: ["session.command.finished"],
-                      maxBytes: SESSION_EVENT_MCP_MAX_BYTES * 4,
-                    },
-                  );
-                  return { events: page.events, hasMore: page.hasMore };
-                },
-                readOwnPendingUpdateKinds: async () =>
-                  (
-                    await listOutstandingSessionSystemUpdates(
-                      deps.db,
-                      grant.workspaceId,
-                      callerSessionId,
-                    )
-                  ).map((update) => update.kind),
-                subscribe: (targetSessionId, onEvents) =>
-                  deps.bus.subscribe(grant.workspaceId, targetSessionId, onEvents),
-              },
-            });
-          }
-
-          command =
-            (await getSessionBackgroundCommand(deps.db, {
-              accountId: grant.accountId,
-              workspaceId: grant.workspaceId,
-              sessionId: callerSessionId,
-              commandId,
-            })) ?? command;
-          const isTerminal = terminal();
-          const ownPendingUpdateKinds = (
-            await listOutstandingSessionSystemUpdates(deps.db, grant.workspaceId, callerSessionId)
-          ).map((update) => update.kind);
-          const ownPendingUpdates = ownPendingUpdateKinds.length;
-          if (waitResult) {
-            // A bounded wait may cross a host/session revocation boundary. The
-            // durable command and pending-input reads above are not returned
-            // until the target is authorized again at the response boundary.
+          async ({ commandId, cursor, waitSeconds, maxOutputBytes }, extra) => {
             await authorizeFirstPartySession(deps, grant, callerSessionId, "session.events.read");
-          }
-          const timedOut =
-            (waitResult?.timedOut ?? false) && !isTerminal && ownPendingUpdates === 0;
-          return json({
-            command,
-            terminal: isTerminal,
-            waitedMs: waitResult?.waitedMs ?? 0,
-            timedOut,
-            aborted: waitResult?.aborted ?? false,
-            liveFanout: waitResult?.liveFanout ?? true,
-            ownPendingUpdates,
-            ownPendingUpdateKinds,
-            ...(isTerminal
-              ? {
-                  outputLocator: {
-                    eventType: "sandbox.command.output.delta",
+            let initialRead = true;
+            return json(
+              await readCommandWithWait({
+                commandId,
+                waitSeconds:
+                  waitSeconds ?? (toolName === "command_wait" ? COMMAND_WAIT_DEFAULT_SECONDS : 0),
+                ...(maxOutputBytes === undefined ? {} : { maxOutputBytes }),
+                ...(extra?.signal === undefined ? {} : { signal: extra.signal }),
+                read: async () => {
+                  if (!initialRead)
+                    await authorizeFirstPartySession(
+                      deps,
+                      grant,
+                      callerSessionId,
+                      "session.events.read",
+                    );
+                  initialRead = false;
+                  return await readSessionBackgroundCommandOutput(deps.db, {
+                    accountId: grant.accountId,
+                    workspaceId: grant.workspaceId,
+                    sessionId: callerSessionId,
                     commandId,
-                  },
-                }
-              : {}),
-            nextAction: isTerminal
-              ? ownPendingUpdates > 0
-                ? "End this turn to receive the queued command result or other machine input."
-                : "The command is terminal; inspect output events only if more detail is needed."
-              : ownPendingUpdates > 0
-                ? "End this turn to receive pending machine input."
-                : waitResult?.timedOut
-                  ? "Do not immediately repeat this short wait without new completion evidence; use wait_for_input for a long or uncertain wait."
-                  : "The wait was aborted; follow the newer session control or input.",
-          });
-        },
-      );
+                    ...(cursor === undefined ? {} : { cursor }),
+                    ...(maxOutputBytes === undefined ? {} : { maxOutputBytes }),
+                  });
+                },
+                subscribe: (onEvents) =>
+                  deps.bus.subscribe(grant.workspaceId, callerSessionId, onEvents),
+              }),
+            );
+          },
+        );
+      }
     }
   }
 
@@ -5142,7 +5270,12 @@ function registerWorkspaceOrchestrationTools(
           ),
         instructions: z4.string().min(1).max(SESSION_INSTRUCTIONS_MAX_CHARACTERS).optional(),
         goal: z4.unknown().optional(),
-        resources: z4.array(z4.unknown()).optional(),
+        resources: z4
+          .array(z4.unknown())
+          .optional()
+          .describe(
+            "Omit to inherit parent repositories only. Files are never inherited automatically; explicitly include file resources to attach them. An empty array inherits no resources.",
+          ),
         tools: z4.array(z4.unknown()).optional(),
         mcpServers: z4.array(z4.unknown()).optional(),
         variableSetId: z4.string().uuid().optional(),
@@ -6303,6 +6436,7 @@ const SESSION_DISCOVERY_PREVIEW_OMISSION_REASON = "aggregatePreviewBudget" as co
 const SESSION_DISCOVERY_PAGE_MAX_BYTES = 128_000;
 const SESSION_DISCOVERY_PREVIEW_DRILL_DOWN_TOOL = "session_events" as const;
 const SESSION_DISCOVERY_PREVIEW_DRILL_DOWN_BASE_INPUT = {
+  view: "debug",
   direction: "before",
   limit: 1,
   mode: "monitoring",