@opengeni/api-router 0.22.2 → 0.23.1

package/src/mcp/server.ts

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import {
   CreateScheduledTaskRequest,
   DEFAULT_FIRST_PARTY_MCP_TOOLS,
@@ -24,6 +24,7 @@ import {
   type SessionAuthorizationOperation,
   type SessionAuthorizationSurface,
   type Session,
+  type ScheduledTask,
   UpdateScheduledTaskRequest,
   normalizeWorkspaceArtifactSlug,
   WORKSPACE_ARTIFACT_HTML_MAX_UTF8_BYTES,
@@ -33,6 +34,7 @@ import {
   countVariableSets,
   beginRigChangeVerificationAttempt,
   createVariableSet,
+  decryptVariableSetValue,
   deleteScheduledTask,
   encryptVariableSetValue,
   getSession,
@@ -56,6 +58,8 @@ import {
   listRigVersionMonitoringSummaries,
   listSocialPosts,
   recordAuditEvent,
+  removeEnrollment,
+  readVariableSetSecretAtomically,
   recordSyncedSocialPosts,
   listVariableSets,
   MEMORY_CORRECT_TOOL_DESCRIPTION,
@@ -95,8 +99,10 @@ import type { AnySchema, ZodRawShapeCompat } from "@modelcontextprotocol/sdk/ser
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import * as z4 from "zod/v4";
 import {
+  hasLiteralPermission,
   hasPermission,
   authorizedSocialConnectionsForGrant,
+  requireLiveAgentAttemptAuthorization,
   requireSessionAuthorization,
   requireSessionAuthorizationListScope,
   type ResolvedSessionAuthorization,
@@ -132,17 +138,21 @@ import {
   createValidatedScheduledTask,
   manualScheduledTaskTriggerUsageKey,
   manualScheduledTaskTriggerWorkflowId,
+  scheduledTaskForGrant,
+  scheduledTaskRunForGrant,
   scheduledTaskToolsProvided,
   scheduledTaskTriggerToken,
+  ScheduledTaskSyncError,
   syncCreatedScheduledTask,
   syncUpdatedScheduledTask,
+  validateScheduledTaskTarget,
   validatedScheduledTaskUpdate,
 } from "@opengeni/core";
 import {
-  acceptSessionUserMessage,
+  acceptSessionUserMessageWithOutcome,
   controlAgentSessionWorkstream,
   controlHumanSessionWorkstream,
-  createSessionForRequest,
+  createSessionForRequestWithOutcome,
   SessionSpawnDeniedError,
   sessionSpawnDenialEnvelope,
   sendAgentSessionMessage,
@@ -170,6 +180,12 @@ import {
   boundRigDetailMcp,
   SESSION_EVENT_MCP_MAX_BYTES,
 } from "./session-view";
+import { mcpMutationReceipt, sessionCreateMutationReceipt } from "./receipts";
+import {
+  boundScheduledTaskDetailMcp,
+  boundScheduledTaskMcpPage,
+  scheduledTaskMcpSummary,
+} from "./scheduled-task-view";
 import type { ToolspaceMcpSurface } from "./toolspace";
 import { ensureSessionGroupReady as ensureViewerSessionGroupReady } from "../sandbox/viewer";
 import {
@@ -205,13 +221,17 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   memory_search: { sessionRequired: true, allOf: ["documents:search"] },
   memory_save: { sessionRequired: true, allOf: ["documents:search"] },
   memory_correct: { sessionRequired: true, allOf: ["documents:search"] },
-  preference_registry_summary: { sessionRequired: true, allOf: ["workspace:read"] },
+  preference_registry_summary: {
+    sessionRequired: true,
+    allOf: ["workspace:read"],
+  },
   preference_registry_get: { sessionRequired: true, allOf: ["workspace:read"] },
   sandboxes_list: { sessionRequired: true, allOf: ["sessions:read"] },
   sandbox_attach: { sessionRequired: true, allOf: ["sessions:control"] },
   sandbox_swap: { sessionRequired: true, allOf: ["sessions:control"] },
   run_on: { sessionRequired: true, allOf: ["sessions:control"] },
   sandbox_provision: { sessionRequired: true, allOf: ["sessions:control"] },
+  connected_machine_remove: { allOf: ["enrollments:manage"] },
   rig_list: { allOf: ["rigs:use"] },
   rig_get: { allOf: ["rigs:use"] },
   rig_propose_change: { allOf: ["rigs:use"] },
@@ -226,10 +246,16 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   session_resume: { allOf: ["sessions:control"] },
   session_steer: { sessionRequired: true, allOf: ["sessions:control"] },
   set_other_session_title: { allOf: ["sessions:control"] },
-  variable_set_list: { allOf: ["variable-sets:use"] },
-  environment_list: { allOf: ["variable-sets:use"] },
-  variable_set_set_variable: { allOf: ["variable-sets:manage"] },
-  environment_set_variable: { allOf: ["variable-sets:manage"] },
+  variable_set_list: { allOf: ["variable-sets:list", "secrets:list"] },
+  environment_list: { allOf: ["variable-sets:list", "secrets:list"] },
+  variable_set_get_variable: {
+    sessionRequired: true,
+    allOf: ["variable-sets:read", "secrets:read"],
+  },
+  variable_set_set_variable: {
+    allOf: ["variable-sets:write", "secrets:write"],
+  },
+  environment_set_variable: { allOf: ["variable-sets:write", "secrets:write"] },
   github_connect_link: { allOf: ["github:use"] },
   github_repositories_list: { allOf: ["github:use"] },
   social_connections_list: { allOf: ["connections:read"] },
@@ -244,15 +270,21 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   // Publishes under the user's identity: connections:write keeps it out of the
   // default agent permission set, unlike the read-only social tools above.
   social_post_reply: { allOf: ["connections:write"] },
-  scheduled_tasks_list: { anyOf: ["scheduled_tasks:manage", "scheduled_tasks:run"] },
-  scheduled_tasks_get: { anyOf: ["scheduled_tasks:manage", "scheduled_tasks:run"] },
+  scheduled_tasks_list: {
+    anyOf: ["scheduled_tasks:manage", "scheduled_tasks:run"],
+  },
+  scheduled_tasks_get: {
+    anyOf: ["scheduled_tasks:manage", "scheduled_tasks:run"],
+  },
   scheduled_tasks_create: { allOf: ["scheduled_tasks:manage"] },
   scheduled_tasks_update: { allOf: ["scheduled_tasks:manage"] },
   scheduled_tasks_pause: { allOf: ["scheduled_tasks:manage"] },
   scheduled_tasks_resume: { allOf: ["scheduled_tasks:manage"] },
   scheduled_tasks_trigger: { allOf: ["scheduled_tasks:run"] },
   scheduled_tasks_delete: { allOf: ["scheduled_tasks:manage"] },
-  scheduled_task_runs_list: { anyOf: ["scheduled_tasks:manage", "scheduled_tasks:run"] },
+  scheduled_task_runs_list: {
+    anyOf: ["scheduled_tasks:manage", "scheduled_tasks:run"],
+  },
   slack_bot_list_channels: { allOf: ["connections:read"] },
   slack_bot_channel_history: { allOf: ["connections:read"] },
   slack_bot_thread_replies: { allOf: ["connections:read"] },
@@ -435,6 +467,9 @@ export function buildOpenGeniMcpServer(
   if (!toolspaceMode && sessionId !== null && deps.settings.sandboxSelfhostedEnabled) {
     registerFleetTools(server, deps, grant, sessionId, json);
   }
+  if (!toolspaceMode && can("enrollments:manage") && deps.settings.sandboxSelfhostedEnabled) {
+    registerConnectedMachineTools(server, deps, grant, json);
+  }
   if (!toolspaceMode) {
     registerRigTools(server, deps, grant, can, sessionId, json);
     registerSlackBotTools(server, deps, grant, sessionId, json);
@@ -452,7 +487,7 @@ export function buildOpenGeniMcpServer(
   // session by setting a narrower session.firstPartyMcpPermissions (capped to
   // the creator's own grant); operators still cap what any session can be given.
   registerWorkspaceOrchestrationTools(server, deps, grant, can, sessionId, toolspaceMode, json);
-  registerVariableSetTools(server, deps, grant, can, json);
+  registerVariableSetTools(server, deps, grant, can, sessionId, toolspaceMode, json);
   if (can("github:use")) {
     registerGitHubConnectTool(server, deps, grant, options, json);
   }
@@ -620,10 +655,17 @@ export function buildOpenGeniMcpServer(
         const authority = await requireAuthorizedSocialConnection(connectionId);
         const result = await socialSearchLive(
           deps,
-          { workspaceId: grant.workspaceId, connectionId, subjectId: authority.subjectId },
+          {
+            workspaceId: grant.workspaceId,
+            connectionId,
+            subjectId: authority.subjectId,
+          },
           { query, subreddit, limit },
         );
-        return json({ provider: result.connection.provider, posts: result.posts });
+        return json({
+          provider: result.connection.provider,
+          posts: result.posts,
+        });
       },
     );
 
@@ -642,10 +684,17 @@ export function buildOpenGeniMcpServer(
         const authority = await requireAuthorizedSocialConnection(connectionId);
         const result = await socialMentionsLive(
           deps,
-          { workspaceId: grant.workspaceId, connectionId, subjectId: authority.subjectId },
+          {
+            workspaceId: grant.workspaceId,
+            connectionId,
+            subjectId: authority.subjectId,
+          },
           { sinceId, limit },
         );
-        return json({ provider: result.connection.provider, posts: result.posts });
+        return json({
+          provider: result.connection.provider,
+          posts: result.posts,
+        });
       },
     );
 
@@ -664,10 +713,17 @@ export function buildOpenGeniMcpServer(
         const authority = await requireAuthorizedSocialConnection(connectionId);
         const result = await socialThreadLive(
           deps,
-          { workspaceId: grant.workspaceId, connectionId, subjectId: authority.subjectId },
+          {
+            workspaceId: grant.workspaceId,
+            connectionId,
+            subjectId: authority.subjectId,
+          },
           { id, limit },
         );
-        return json({ provider: result.connection.provider, posts: result.posts });
+        return json({
+          provider: result.connection.provider,
+          posts: result.posts,
+        });
       },
     );
   }
@@ -690,7 +746,11 @@ export function buildOpenGeniMcpServer(
         const authority = await requireAuthorizedSocialConnection(connectionId);
         const result = await socialOwnPostsLive(
           deps,
-          { workspaceId: grant.workspaceId, connectionId, subjectId: authority.subjectId },
+          {
+            workspaceId: grant.workspaceId,
+            connectionId,
+            subjectId: authority.subjectId,
+          },
           { limit },
         );
         // A post without a provider timestamp is skipped rather than recorded
@@ -736,7 +796,11 @@ export function buildOpenGeniMcpServer(
         const authority = await requireAuthorizedSocialConnection(connectionId);
         const result = await socialPostReply(
           deps,
-          { workspaceId: grant.workspaceId, connectionId, subjectId: authority.subjectId },
+          {
+            workspaceId: grant.workspaceId,
+            connectionId,
+            subjectId: authority.subjectId,
+          },
           { inReplyToId, text },
         );
         // Outbound publishes leave a durable, secret-free receipt (house
@@ -769,22 +833,47 @@ export function buildOpenGeniMcpServer(
     server.registerTool(
       "scheduled_tasks_list",
       {
-        description: "List scheduled tasks.",
-        inputSchema: { limit: z4.number().int().positive().optional() },
+        description:
+          "List compact scheduled-task summaries. Prompts, goal text, resource/tool bodies, and metadata values are represented by byte/count facts; page with offset and use scheduled_tasks_get for a bounded explicit detail projection.",
+        inputSchema: {
+          limit: z4.number().int().positive().max(50).optional(),
+          offset: z4.number().int().nonnegative().max(10_000).optional(),
+        },
+      },
+      async ({ limit: requestedLimit, offset: requestedOffset }) => {
+        const limit = requestedLimit ?? 25;
+        const offset = requestedOffset ?? 0;
+        const rows = await listScheduledTasks(deps.db, grant.workspaceId, limit + 1, offset);
+        return json(
+          boundScheduledTaskMcpPage({
+            tasks: rows.slice(0, limit).map((task) => scheduledTaskForGrant(task, grant)),
+            limit,
+            offset,
+            sourceHasMore: rows.length > limit,
+          }),
+        );
       },
-      async ({ limit }) =>
-        json({
-          tasks: await listScheduledTasks(deps.db, grant.workspaceId, limit ?? 100),
-        }),
     );
 
     server.registerTool(
       "scheduled_tasks_get",
       {
-        description: "Get one scheduled task.",
-        inputSchema: { id: z4.string().uuid() },
+        description:
+          "Get one scheduled task. The default is the same compact summary used by scheduled_tasks_list; pass includeEntity=true for a bounded projection with an 8 KiB prompt preview, bounded goal fields, resource/tool identity previews, and metadata keys without values.",
+        inputSchema: {
+          id: z4.string().uuid(),
+          includeEntity: z4.boolean().optional(),
+        },
+      },
+      async ({ id, includeEntity }) => {
+        const task = scheduledTaskForGrant(
+          await requireScheduledTask(deps.db, grant.workspaceId, id),
+          grant,
+        );
+        return json(
+          includeEntity ? boundScheduledTaskDetailMcp(task) : scheduledTaskMcpSummary(task),
+        );
       },
-      async ({ id }) => json(await requireScheduledTask(deps.db, grant.workspaceId, id)),
     );
 
     server.registerTool(
@@ -795,6 +884,7 @@ export function buildOpenGeniMcpServer(
           name: z4.string(),
           schedule: z4.unknown(),
           runMode: z4.string().optional(),
+          targetSessionId: z4.string().uuid().nullable().optional(),
           overlapPolicy: z4.string().optional(),
           agentConfig: z4.unknown(),
           status: z4.string().optional(),
@@ -823,13 +913,29 @@ export function buildOpenGeniMcpServer(
           grant,
           payload,
           toolsProvided: scheduledTaskToolsProvided(args),
+          sessionAuthorization: deps.sessionAuthorization,
+          authorizationSurface: "first_party_mcp",
         });
-        await syncCreatedScheduledTask({
-          db: deps.db,
-          workflowClient: deps.workflowClient,
-          task,
-        });
-        return json(task);
+        try {
+          await syncCreatedScheduledTask({
+            db: deps.db,
+            workflowClient: deps.workflowClient,
+            task,
+          });
+        } catch (error) {
+          if (!(error instanceof ScheduledTaskSyncError) || error.persistenceRestored) {
+            throw error;
+          }
+          return json(
+            scheduledTaskReceipt("scheduled_tasks_create", task, "partial_failure", true, {
+              partialFailure: { stage: "schedule_sync", retryable: true },
+              warnings: [
+                "The task database record committed, but Temporal schedule synchronization failed.",
+              ],
+            }),
+          );
+        }
+        return json(scheduledTaskReceipt("scheduled_tasks_create", task, "created", true));
       },
     );
 
@@ -842,6 +948,7 @@ export function buildOpenGeniMcpServer(
           name: z4.string().optional(),
           schedule: z4.unknown().optional(),
           runMode: z4.string().optional(),
+          targetSessionId: z4.string().uuid().nullable().optional(),
           overlapPolicy: z4.string().optional(),
           agentConfig: z4.unknown().optional(),
           status: z4.string().optional(),
@@ -867,6 +974,8 @@ export function buildOpenGeniMcpServer(
           existing,
           payload,
           toolsProvided: scheduledTaskToolsProvided(raw),
+          sessionAuthorization: deps.sessionAuthorization,
+          authorizationSurface: "first_party_mcp",
         });
         const task = await updateScheduledTask(deps.db, grant.workspaceId, id, update);
         await syncUpdatedScheduledTask({
@@ -875,7 +984,7 @@ export function buildOpenGeniMcpServer(
           previous,
           task,
         });
-        return json(task);
+        return json(scheduledTaskForGrant(task, grant));
       },
     );
 
@@ -897,7 +1006,7 @@ export function buildOpenGeniMcpServer(
           previous,
           task,
         });
-        return json(task);
+        return json(scheduledTaskForGrant(task, grant));
       },
     );
 
@@ -919,7 +1028,7 @@ export function buildOpenGeniMcpServer(
           previous,
           task,
         });
-        return json(task);
+        return json(scheduledTaskForGrant(task, grant));
       },
     );
 
@@ -935,6 +1044,18 @@ export function buildOpenGeniMcpServer(
       },
       async ({ id, triggerId }) => {
         const task = await requireScheduledTask(deps.db, grant.workspaceId, id);
+        await validateScheduledTaskTarget({
+          db: deps.db,
+          sessionAuthorization: deps.sessionAuthorization,
+          authorizationSurface: "first_party_mcp",
+          grant,
+          targetSessionId: task.targetSessionId,
+          runMode: task.runMode,
+          variableSetId: task.variableSetId,
+          rigId: task.rigId,
+          agentConfig: task.agentConfig,
+          missingTargetStatus: 404,
+        });
         await requireLimit(deps, {
           accountId: grant.accountId,
           workspaceId: grant.workspaceId,
@@ -955,18 +1076,36 @@ export function buildOpenGeniMcpServer(
           triggerWorkflowId,
           initiator: { kind: "subject", subjectId: grant.subjectId },
         });
-        await recordWorkspaceUsage(deps, {
-          accountId: grant.accountId,
-          workspaceId: grant.workspaceId,
-          subjectId: grant.subjectId,
-          eventType: "agent_run.created",
-          quantity: 1,
-          unit: "run",
-          sourceResourceType: "scheduled_task",
-          sourceResourceId: task.id,
-          idempotencyKey: agentRunUsageIdempotencyKey,
-        });
-        return json(task);
+        try {
+          await recordWorkspaceUsage(deps, {
+            accountId: grant.accountId,
+            workspaceId: grant.workspaceId,
+            subjectId: grant.subjectId,
+            eventType: "agent_run.created",
+            quantity: 1,
+            unit: "run",
+            sourceResourceType: "scheduled_task",
+            sourceResourceId: task.id,
+            idempotencyKey: agentRunUsageIdempotencyKey,
+          });
+        } catch {
+          return json(
+            scheduledTaskReceipt("scheduled_tasks_trigger", task, "partial_failure", true, {
+              partialFailure: { stage: "usage_recording", retryable: true },
+              warnings: [
+                "The Temporal run trigger completed, but usage recording failed; retry with the same triggerId.",
+              ],
+              idempotencyStatus: triggerId ? "unknown" : "not_requested",
+              facts: { triggerWorkflowId },
+            }),
+          );
+        }
+        return json(
+          scheduledTaskReceipt("scheduled_tasks_trigger", task, "triggered", true, {
+            idempotencyStatus: triggerId ? "unknown" : "not_requested",
+            facts: { triggerWorkflowId },
+          }),
+        );
       },
     );
 
@@ -981,8 +1120,28 @@ export function buildOpenGeniMcpServer(
         await deps.workflowClient.deleteScheduledTaskSchedule({
           temporalScheduleId: task.temporalScheduleId,
         });
-        await deleteScheduledTask(deps.db, grant.workspaceId, id);
-        return json({ ok: true });
+        try {
+          await deleteScheduledTask(deps.db, grant.workspaceId, id);
+        } catch {
+          return json(
+            scheduledTaskReceipt("scheduled_tasks_delete", task, "partial_failure", true, {
+              partialFailure: { stage: "database_delete", retryable: true },
+              warnings: [
+                "The Temporal schedule was deleted, but the task database record remains.",
+              ],
+            }),
+          );
+        }
+        return json(
+          mcpMutationReceipt({
+            operation: "scheduled_tasks_delete",
+            committed: true,
+            outcome: "deleted",
+            changed: true,
+            resource: { type: "scheduled_task", id: task.id, state: "deleted" },
+            idempotency: { status: "not_supported" },
+          }),
+        );
       },
     );
 
@@ -997,7 +1156,9 @@ export function buildOpenGeniMcpServer(
       },
       async ({ taskId, limit }) =>
         json({
-          runs: await listScheduledTaskRuns(deps.db, grant.workspaceId, taskId, limit ?? 100),
+          runs: (await listScheduledTaskRuns(deps.db, grant.workspaceId, taskId, limit ?? 100)).map(
+            (run) => scheduledTaskRunForGrant(run, grant),
+          ),
         }),
     );
   }
@@ -1441,10 +1602,27 @@ function registerGoalTools(
           event: { type: "goal.completed", evidence },
         },
       );
+      const changed = events.length > 0;
       if (events.length > 0) {
         await deps.bus.publish(grant.workspaceId, sessionId, events);
       }
-      return json(goal);
+      return json(
+        mcpMutationReceipt({
+          operation: "goal_complete",
+          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 } },
+        }),
+      );
     },
   );
 
@@ -1478,10 +1656,27 @@ function registerGoalTools(
           },
         },
       );
+      const changed = events.length > 0;
       if (events.length > 0) {
         await deps.bus.publish(grant.workspaceId, sessionId, events);
       }
-      return json(goal);
+      return json(
+        mcpMutationReceipt({
+          operation: "goal_pause",
+          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 } },
+        }),
+      );
     },
   );
 }
@@ -1599,7 +1794,11 @@ function registerWorkspaceArtifactTools(
       const actualHash = createHash("sha256").update(object.bytes).digest("hex");
       if (actualHash !== ref.version.contentSha256)
         throw new Error("Artifact content failed integrity verification");
-      return json({ detail, version: ref.version, html: new TextDecoder().decode(object.bytes) });
+      return json({
+        detail,
+        version: ref.version,
+        html: new TextDecoder().decode(object.bytes),
+      });
     },
   );
 
@@ -1761,6 +1960,38 @@ function registerPreferenceRegistryTools(
 
 const MemoryKindSchema = z4.enum(["preference", "semantic", "procedural", "decision", "episodic"]);
 
+function scheduledTaskReceipt(
+  operation: string,
+  task: ScheduledTask,
+  outcome: "created" | "updated" | "unchanged" | "triggered" | "partial_failure",
+  changed: boolean,
+  options: {
+    partialFailure?: { stage: string; retryable: boolean };
+    warnings?: string[];
+    idempotencyStatus?: "not_supported" | "not_requested" | "applied" | "replayed" | "unknown";
+    facts?: Record<string, string | number | boolean | null>;
+  } = {},
+) {
+  return mcpMutationReceipt({
+    operation,
+    committed: true,
+    outcome,
+    changed,
+    resource: {
+      type: "scheduled_task",
+      id: task.id,
+      version: task.updatedAt,
+      state: task.status,
+    },
+    timestamp: task.updatedAt,
+    idempotency: { status: options.idempotencyStatus ?? "not_supported" },
+    ...(options.partialFailure ? { partialFailure: options.partialFailure } : {}),
+    ...(options.warnings ? { warnings: options.warnings } : {}),
+    ...(options.facts ? { facts: options.facts } : {}),
+    nextAction: { tool: "scheduled_tasks_get", arguments: { id: task.id } },
+  });
+}
+
 function memoryPreview(text: string): string {
   const normalized = text.replace(/\s+/g, " ").trim();
   return normalized.length <= 120 ? normalized : `${normalized.slice(0, 119)}…`;
@@ -1836,7 +2067,46 @@ function registerMemoryTools(
           },
         },
       ]);
-      return json(result);
+      const changed = !result.deduped || result.updated || result.superseded !== null;
+      const outcome =
+        result.updated || result.superseded !== null
+          ? "updated"
+          : result.deduped
+            ? "unchanged"
+            : "created";
+      return json(
+        mcpMutationReceipt({
+          operation: "memory_save",
+          committed: true,
+          outcome,
+          changed,
+          resource: {
+            type: "knowledge_memory",
+            id: result.memory.id,
+            state: result.memory.status,
+          },
+          relatedResources: result.superseded
+            ? [
+                {
+                  type: "knowledge_memory",
+                  id: result.superseded.id,
+                  state: result.superseded.status,
+                },
+              ]
+            : undefined,
+          timestamp: result.memory.updatedAt,
+          idempotency: { status: "not_supported" },
+          warnings: !result.embedded
+            ? ["Memory committed without a vector embedding; keyword search remains available."]
+            : [],
+          facts: {
+            deduped: result.deduped,
+            dedupeReason: result.dedupeReason,
+            updatedInPlace: result.updated,
+            embedded: result.embedded,
+          },
+        }),
+      );
     },
   );
 
@@ -1881,7 +2151,31 @@ function registerMemoryTools(
           },
         },
       ]);
-      return json(result);
+      return json(
+        mcpMutationReceipt({
+          operation: "memory_correct",
+          committed: true,
+          outcome: "updated",
+          changed: true,
+          resource: {
+            type: "knowledge_memory",
+            id: result.memory.id,
+            state: result.memory.status,
+          },
+          relatedResources: result.replacement
+            ? [
+                {
+                  type: "knowledge_memory",
+                  id: result.replacement.id,
+                  state: result.replacement.status,
+                },
+              ]
+            : undefined,
+          timestamp: (result.replacement ?? result.memory).updatedAt,
+          idempotency: { status: "not_supported" },
+          facts: { correctionAction: result.action },
+        }),
+      );
     },
   );
 }
@@ -1928,7 +2222,7 @@ function registerFleetTools(
     "sandboxes_list",
     {
       description:
-        "List the sandboxes this session can run on: its own session sandbox plus enrolled selfhosted machines. `liveness` is conservative: online requires observed provider existence and verified workspace readiness. An idle session-home sandbox may report offline/cold/draining and still wake or restore on the next ordinary sandbox operation; never infer that shell/files are unavailable from list liveness alone—only a typed operation/attach failure proves that. Provider, lease, route, archive, restore, workspace, lease epoch, and route epoch are also reported separately. Use an entry `id` as an attach/swap/run_on target.",
+        "List the sandboxes this session can run on: its own session sandbox plus enrolled selfhosted machines. `operationAvailability` is authoritative for ordinary shell/files use: `wakeable` means the next ordinary operation will wake or restore the idle managed home sandbox, even when `liveness=offline`, `leaseLiveness=cold|draining`, or `attachable=false`. `attachable` describes an already-live swap target, not ordinary operation availability. `recovering` requires a bounded retry/typed recovery result; `unavailable` is not usable. Provider, lease, route, archive, restore, workspace, lease epoch, and route epoch remain separate truth dimensions. Use an entry `id` as an attach/swap/run_on target.",
       inputSchema: {},
     },
     async () => json(await listFleet(services, await fleetContext())),
@@ -2000,6 +2294,45 @@ function registerFleetTools(
   );
 }
 
+// Workspace-admin/operator surface for removing a connected machine. This is
+// deliberately separate from the session-scoped fleet tools: a worker can list,
+// attach, or run on a machine only with session authority, while removal requires
+// the explicit high-trust enrollments:manage permission and never accepts a
+// sandbox id. A Modal record therefore cannot be removed through this operation.
+function registerConnectedMachineTools(
+  server: McpServer,
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  json: JsonResult,
+): void {
+  server.registerTool(
+    "connected_machine_remove",
+    {
+      description:
+        "Remove one enrolled self-hosted machine while it is offline. Access is revoked, future heartbeat/reconnect credentials are rejected, session/route/lease/archive history is retained, and a fresh human-approved device-flow enrollment is required to reconnect. Pass the enrollmentId from the Machines surface, never a Modal sandbox id. Blocked outcomes include the exact active dependency and the action needed before retrying.",
+      inputSchema: {
+        enrollmentId: z4.string().uuid(),
+        expectedUpdatedAt: z4.string().datetime({ offset: true }).optional(),
+        idempotencyKey: z4.string().trim().min(1).max(200).optional(),
+      },
+    },
+    async ({ enrollmentId, expectedUpdatedAt, idempotencyKey }) => {
+      const result = await removeEnrollment(deps.db, {
+        accountId: grant.accountId,
+        workspaceId: grant.workspaceId,
+        enrollmentId,
+        operationKey: idempotencyKey?.trim() || randomUUID(),
+        ...(expectedUpdatedAt ? { expectedUpdatedAt } : {}),
+        subjectId: grant.subjectId,
+      });
+      if (!result) {
+        throw new Error("machine enrollment not found in this workspace");
+      }
+      return json({ revoked: result.removed, ...result });
+    },
+  );
+}
+
 async function beginMcpRigVerificationAttempt(
   deps: ApiRouteDeps,
   workspaceId: string,
@@ -2101,12 +2434,60 @@ function registerRigTools(
           sessionId ? { proposedBy: `session:${sessionId}` } : {},
         );
         const verifying = await beginMcpRigVerificationAttempt(deps, grant.workspaceId, change.id);
-        await deps.workflowClient.startRigVerification({
-          workspaceId: grant.workspaceId,
-          changeId: change.id,
-          workflowId: `rig-verification-change-${change.id}-attempt-${verificationAttempt(verifying)}`,
-        });
-        return json({ change: verifying, verificationStarted: true });
+        const attempt = verificationAttempt(verifying);
+        try {
+          await deps.workflowClient.startRigVerification({
+            workspaceId: grant.workspaceId,
+            changeId: change.id,
+            workflowId: `rig-verification-change-${change.id}-attempt-${attempt}`,
+          });
+        } catch {
+          return json(
+            mcpMutationReceipt({
+              operation: "rig_propose_change",
+              committed: true,
+              outcome: "partial_failure",
+              changed: true,
+              resource: {
+                type: "rig_change",
+                id: verifying.id,
+                version: verifying.updatedAt,
+                state: verifying.status,
+              },
+              relatedResources: [{ type: "rig", id: rig.id }],
+              timestamp: verifying.updatedAt,
+              idempotency: { status: "not_supported" },
+              partialFailure: {
+                stage: "verification_workflow_start",
+                retryable: true,
+              },
+              warnings: [
+                "The rig change and verifying transition committed, but verification workflow start failed.",
+              ],
+              facts: { verificationAttempt: attempt },
+              nextAction: { tool: "rig_get", arguments: { rigId: rig.id } },
+            }),
+          );
+        }
+        return json(
+          mcpMutationReceipt({
+            operation: "rig_propose_change",
+            committed: true,
+            outcome: "created",
+            changed: true,
+            resource: {
+              type: "rig_change",
+              id: verifying.id,
+              version: verifying.updatedAt,
+              state: verifying.status,
+            },
+            relatedResources: [{ type: "rig", id: rig.id }],
+            timestamp: verifying.updatedAt,
+            idempotency: { status: "not_supported" },
+            facts: { verificationStarted: true, verificationAttempt: attempt },
+            nextAction: { tool: "rig_get", arguments: { rigId: rig.id } },
+          }),
+        );
       },
     );
 
@@ -2129,12 +2510,63 @@ function registerRigTools(
             grant.workspaceId,
             change.id,
           );
-          await deps.workflowClient.startRigVerification({
-            workspaceId: grant.workspaceId,
-            changeId: change.id,
-            workflowId: `rig-verification-change-${change.id}-attempt-${verificationAttempt(verifying)}`,
-          });
-          return json({ ok: true, changeId: change.id });
+          const attempt = verificationAttempt(verifying);
+          try {
+            await deps.workflowClient.startRigVerification({
+              workspaceId: grant.workspaceId,
+              changeId: change.id,
+              workflowId: `rig-verification-change-${change.id}-attempt-${attempt}`,
+            });
+          } catch {
+            return json(
+              mcpMutationReceipt({
+                operation: "rig_verify",
+                committed: true,
+                outcome: "partial_failure",
+                changed: true,
+                resource: {
+                  type: "rig_change",
+                  id: verifying.id,
+                  version: verifying.updatedAt,
+                  state: verifying.status,
+                },
+                relatedResources: [{ type: "rig", id: rig.id }],
+                timestamp: verifying.updatedAt,
+                idempotency: { status: "not_supported" },
+                partialFailure: {
+                  stage: "verification_workflow_start",
+                  retryable: true,
+                },
+                warnings: [
+                  "The verifying transition committed, but verification workflow start failed.",
+                ],
+                facts: { verificationAttempt: attempt },
+                nextAction: { tool: "rig_get", arguments: { rigId: rig.id } },
+              }),
+            );
+          }
+          return json(
+            mcpMutationReceipt({
+              operation: "rig_verify",
+              committed: true,
+              outcome: "accepted",
+              changed: true,
+              resource: {
+                type: "rig_change",
+                id: verifying.id,
+                version: verifying.updatedAt,
+                state: verifying.status,
+              },
+              relatedResources: [{ type: "rig", id: rig.id }],
+              timestamp: verifying.updatedAt,
+              idempotency: { status: "not_supported" },
+              facts: {
+                verificationStarted: true,
+                verificationAttempt: attempt,
+              },
+              nextAction: { tool: "rig_get", arguments: { rigId: rig.id } },
+            }),
+          );
         }
         if (!rig.activeVersion) {
           throw new Error("rig has no active version");
@@ -2144,7 +2576,23 @@ function registerRigTools(
           versionId: rig.activeVersion.id,
           workflowId: `rig-verification-version-${rig.activeVersion.id}-${crypto.randomUUID()}`,
         });
-        return json({ ok: true, versionId: rig.activeVersion.id });
+        return json(
+          mcpMutationReceipt({
+            operation: "rig_verify",
+            committed: true,
+            outcome: "accepted",
+            changed: true,
+            resource: {
+              type: "rig_version",
+              id: rig.activeVersion.id,
+              version: rig.activeVersion.version,
+              state: "verification_started",
+            },
+            relatedResources: [{ type: "rig", id: rig.id }],
+            idempotency: { status: "not_supported" },
+            nextAction: { tool: "rig_get", arguments: { rigId: rig.id } },
+          }),
+        );
       },
     );
   }
@@ -2163,8 +2611,36 @@ function registerRigTools(
       async ({ rigId, changeId }) => {
         const rig = await requireRigForApi(deps.db, grant.workspaceId, rigId);
         const change = await requireRigChangeForApi(deps.db, grant.workspaceId, rig.id, changeId);
+        const promoted = await promoteVerifiedDefinitionEditChangeForApi(
+          { db: deps.db },
+          grant,
+          rig,
+          change,
+        );
         return json(
-          await promoteVerifiedDefinitionEditChangeForApi({ db: deps.db }, grant, rig, change),
+          mcpMutationReceipt({
+            operation: "rig_promote",
+            committed: true,
+            outcome: "updated",
+            changed: true,
+            resource: {
+              type: "rig_version",
+              id: promoted.version.id,
+              version: promoted.version.version,
+              state: "active",
+            },
+            relatedResources: [
+              {
+                type: "rig_change",
+                id: promoted.change.id,
+                state: promoted.change.status,
+              },
+              { type: "rig", id: rig.id },
+            ],
+            timestamp: promoted.version.createdAt,
+            idempotency: { status: "not_supported" },
+            nextAction: { tool: "rig_get", arguments: { rigId: rig.id } },
+          }),
         );
       },
     );
@@ -2384,7 +2860,10 @@ function registerWorkspaceOrchestrationTools(
                   compactSessionEventResult(
                     event,
                     latestClass!,
-                    dbPage.coveredSequence ?? { first: event.sequence, last: event.sequence },
+                    dbPage.coveredSequence ?? {
+                      first: event.sequence,
+                      last: event.sequence,
+                    },
                   ),
                 )
               : null,
@@ -2508,8 +2987,13 @@ function registerWorkspaceOrchestrationTools(
           if (callerSessionId !== null) {
             await authorizeFirstPartySession(deps, grant, callerSessionId, "session.child.create");
           }
-          const created = await createSessionForRequest(deps, grant, grant.workspaceId, args);
-          return json(await withMcpEffectivePolicy(deps, grant.workspaceId, created));
+          const result = await createSessionForRequestWithOutcome(
+            deps,
+            grant,
+            grant.workspaceId,
+            args,
+          );
+          return json(sessionCreateMutationReceipt(result, Boolean(args.idempotencyKey)));
         } catch (error) {
           if (error instanceof SessionSpawnDeniedError) {
             return {
@@ -2549,17 +3033,33 @@ function registerWorkspaceOrchestrationTools(
             exactAgentCommandContext(grant, callerSessionId),
             { targetSessionId, text, idempotencyKey },
           );
-          return json({
-            delivered: true,
-            updateId: result.updateId,
-            delivery: "coalesced_internal_update",
-            effectiveState: result.effectiveState,
-            wakeRequested: result.wakeRevision !== null,
-            resumeRequired: result.effectiveState === "paused",
-            replay: result.replay,
-          });
+          return json(
+            mcpMutationReceipt({
+              operation: "session_send_message",
+              committed: true,
+              outcome: result.replay ? "replayed" : "accepted",
+              changed: !result.replay,
+              resource: {
+                type: "session_system_update",
+                id: result.updateId,
+                state: result.effectiveState,
+              },
+              relatedResources: [{ type: "session", id: targetSessionId }],
+              timestamp: result.receipt.createdAt.toISOString(),
+              idempotency: { status: result.replay ? "replayed" : "applied" },
+              facts: {
+                delivery: "coalesced_internal_update",
+                wakeRequested: result.wakeRevision !== null,
+                resumeRequired: result.effectiveState === "paused",
+              },
+              nextAction: {
+                tool: "session_get",
+                arguments: { sessionId: targetSessionId },
+              },
+            }),
+          );
         }
-        const { accepted, turn } = await acceptSessionUserMessage(
+        const { accepted, turn, replay } = await acceptSessionUserMessageWithOutcome(
           deps,
           grant,
           grant.workspaceId,
@@ -2574,7 +3074,30 @@ function registerWorkspaceOrchestrationTools(
             ),
           },
         );
-        return json({ event: accepted, turnId: turn.id });
+        return json(
+          mcpMutationReceipt({
+            operation: "session_send_message",
+            committed: true,
+            outcome: replay ? "replayed" : "accepted",
+            changed: !replay,
+            resource: {
+              type: "session_turn",
+              id: turn.id,
+              version: turn.version,
+              state: turn.status,
+            },
+            relatedResources: [
+              { type: "session", id: targetSessionId },
+              { type: "session_event", id: accepted.id, state: accepted.type },
+            ],
+            timestamp: accepted.occurredAt,
+            idempotency: { status: replay ? "replayed" : "applied" },
+            nextAction: {
+              tool: "session_get",
+              arguments: { sessionId: targetSessionId },
+            },
+          }),
+        );
       },
     );
 
@@ -2701,13 +3224,28 @@ function registerWorkspaceOrchestrationTools(
             exactAgentCommandContext(grant, callerSessionId, "first_party_mcp"),
             { targetSessionId: sessionId, instruction, idempotencyKey },
           );
-          return json({
-            updateId: result.updateId,
-            interruptionCount: result.interruptionCount,
-            stoppingPreviousAttempt: result.interruptionCount > 0,
-            effectiveState: result.effectiveState,
-            replay: result.replay,
-          });
+          return json(
+            mcpMutationReceipt({
+              operation: "session_steer",
+              committed: true,
+              outcome: result.replay ? "replayed" : "updated",
+              changed: !result.replay,
+              resource: {
+                type: "session_system_update",
+                id: result.updateId,
+                state: result.effectiveState,
+              },
+              relatedResources: [{ type: "session", id: sessionId }],
+              timestamp: result.receipt.createdAt.toISOString(),
+              idempotency: { status: result.replay ? "replayed" : "applied" },
+              facts: {
+                interruptionCount: result.interruptionCount,
+                stoppingPreviousAttempt: result.interruptionCount > 0,
+              },
+              updateId: result.updateId,
+              nextAction: { tool: "session_get", arguments: { sessionId } },
+            }),
+          );
         },
       );
     }
@@ -2736,15 +3274,16 @@ function registerWorkspaceOrchestrationTools(
   }
 }
 
-// VariableSet management for manager-style agents. v1 deliberately accepts
-// variable VALUES in plain tool arguments: the calling model is trusted with
-// the secrets it is persisting (see docs/variable-sets.md). Reads stay
-// write-only — responses carry names and metadata, never values.
+// Variable-set management for agents. Generic reads remain metadata-only.
+// Plaintext has one dedicated tool that additionally requires literal
+// secrets:read plus exact live attempt/session authorization.
 function registerVariableSetTools(
   server: McpServer,
   deps: ApiRouteDeps,
   grant: AccessGrant,
   can: (permission: Permission) => boolean,
+  sessionId: string | null,
+  toolspaceMode: boolean,
   json: JsonResult,
 ): void {
   const registerListTool = (name: string, description: string): void => {
@@ -2760,93 +3299,114 @@ function registerVariableSetTools(
       },
     );
   };
-  const setVariableHandler = async ({
-    variableSetId,
-    variableSetName,
-    environmentId,
-    environmentName,
-    name,
-    value,
-  }: {
-    variableSetId?: string | undefined;
-    variableSetName?: string | undefined;
-    environmentId?: string | undefined;
-    environmentName?: string | undefined;
-    name: string;
-    value: string;
-  }) => {
-    const key = requireVariableSetEncryption(deps.settings);
-    const parsedName = VariableSetVariableName.safeParse(name);
-    if (!parsedName.success) {
-      throw new Error("variable set/environment variable names must match ^[A-Z][A-Z0-9_]*$");
-    }
-    assertAllowedVariableSetVariableName(parsedName.data);
-    const targetId = variableSetId ?? environmentId;
-    const targetName = variableSetName ?? environmentName;
-    if ((targetId === undefined) === (targetName === undefined)) {
-      throw new Error(
-        "provide exactly one of variableSetId or variableSetName; deprecated aliases must provide exactly one of environmentId or environmentName",
-      );
-    }
-    const trimmedVariableSetName = targetName?.trim();
-    if (targetName !== undefined && !trimmedVariableSetName) {
-      throw new Error("variable set name is required");
-    }
-    let created = false;
-    let variableSet =
-      targetId !== undefined
-        ? await getVariableSet(deps.db, grant.workspaceId, targetId)
-        : await getVariableSetByName(deps.db, grant.workspaceId, trimmedVariableSetName!);
-    if (!variableSet && targetId !== undefined) {
-      throw new Error("variable set/environment not found");
-    }
-    if (!variableSet) {
-      if ((await countVariableSets(deps.db, grant.workspaceId)) >= MAX_ENVIRONMENTS_PER_WORKSPACE) {
+  const setVariableHandler =
+    (operation: "variable_set_set_variable" | "environment_set_variable") =>
+    async ({
+      variableSetId,
+      variableSetName,
+      environmentId,
+      environmentName,
+      name,
+      value,
+    }: {
+      variableSetId?: string | undefined;
+      variableSetName?: string | undefined;
+      environmentId?: string | undefined;
+      environmentName?: string | undefined;
+      name: string;
+      value: string;
+    }) => {
+      const key = requireVariableSetEncryption(deps.settings);
+      const parsedName = VariableSetVariableName.safeParse(name);
+      if (!parsedName.success) {
+        throw new Error("variable set/environment variable names must match ^[A-Z][A-Z0-9_]*$");
+      }
+      assertAllowedVariableSetVariableName(parsedName.data);
+      const targetId = variableSetId ?? environmentId;
+      const targetName = variableSetName ?? environmentName;
+      if ((targetId === undefined) === (targetName === undefined)) {
         throw new Error(
-          `a workspace supports at most ${MAX_ENVIRONMENTS_PER_WORKSPACE} variable sets`,
+          "provide exactly one of variableSetId or variableSetName; deprecated aliases must provide exactly one of environmentId or environmentName",
         );
       }
-      variableSet = await createVariableSet(deps.db, {
+      const trimmedVariableSetName = targetName?.trim();
+      if (targetName !== undefined && !trimmedVariableSetName) {
+        throw new Error("variable set name is required");
+      }
+      let created = false;
+      let variableSet =
+        targetId !== undefined
+          ? await getVariableSet(deps.db, grant.workspaceId, targetId)
+          : await getVariableSetByName(deps.db, grant.workspaceId, trimmedVariableSetName!);
+      if (!variableSet && targetId !== undefined) {
+        throw new Error("variable set/environment not found");
+      }
+      if (!variableSet) {
+        if (
+          (await countVariableSets(deps.db, grant.workspaceId)) >= MAX_ENVIRONMENTS_PER_WORKSPACE
+        ) {
+          throw new Error(
+            `a workspace supports at most ${MAX_ENVIRONMENTS_PER_WORKSPACE} variable sets`,
+          );
+        }
+        variableSet = await createVariableSet(deps.db, {
+          accountId: grant.accountId,
+          workspaceId: grant.workspaceId,
+          name: trimmedVariableSetName!,
+        });
+        created = true;
+        await recordVariableSetAuditEvent(deps.db, {
+          grant,
+          action: "variable_set.created",
+          variableSetId: variableSet.id,
+        });
+      }
+      const exists = variableSet.variables.some((variable) => variable.name === parsedName.data);
+      if (!exists && variableSet.variables.length >= MAX_VARIABLES_PER_ENVIRONMENT) {
+        throw new Error(
+          `a variable set supports at most ${MAX_VARIABLES_PER_ENVIRONMENT} variables`,
+        );
+      }
+      const metadata = await setVariableSetVariable(deps.db, {
         accountId: grant.accountId,
         workspaceId: grant.workspaceId,
-        name: trimmedVariableSetName!,
+        variableSetId: variableSet.id,
+        name: parsedName.data,
+        valueEncrypted: encryptVariableSetValue(key, value),
       });
-      created = true;
       await recordVariableSetAuditEvent(deps.db, {
         grant,
-        action: "variable_set.created",
+        action: "variable_set.variable.set",
         variableSetId: variableSet.id,
+        variableName: parsedName.data,
       });
-    }
-    const exists = variableSet.variables.some((variable) => variable.name === parsedName.data);
-    if (!exists && variableSet.variables.length >= MAX_VARIABLES_PER_ENVIRONMENT) {
-      throw new Error(`a variable set supports at most ${MAX_VARIABLES_PER_ENVIRONMENT} variables`);
-    }
-    const metadata = await setVariableSetVariable(deps.db, {
-      accountId: grant.accountId,
-      workspaceId: grant.workspaceId,
-      variableSetId: variableSet.id,
-      name: parsedName.data,
-      valueEncrypted: encryptVariableSetValue(key, value),
-    });
-    await recordVariableSetAuditEvent(deps.db, {
-      grant,
-      action: "variable_set.variable.set",
-      variableSetId: variableSet.id,
-      variableName: parsedName.data,
-    });
-    const responseVariableSet = {
-      id: variableSet.id,
-      name: variableSet.name,
-      created,
+      return json(
+        mcpMutationReceipt({
+          operation,
+          committed: true,
+          outcome: exists ? "updated" : "created",
+          changed: true,
+          resource: {
+            type: "variable_set",
+            id: variableSet.id,
+            version: metadata.version,
+            state: "variable_written",
+          },
+          timestamp: metadata.updatedAt,
+          idempotency: { status: "not_supported" },
+          facts: {
+            variableCreated: !exists,
+            variableSetCreated: created,
+            deprecatedAlias: operation === "environment_set_variable",
+          },
+          nextAction: { tool: "variable_set_list", arguments: {} },
+        }),
+      );
     };
-    return json({
-      variableSet: responseVariableSet,
-      environment: responseVariableSet,
-      variable: metadata,
-    });
-  };
-  const registerSetTool = (name: string, description: string): void => {
+  const registerSetTool = (
+    name: "variable_set_set_variable" | "environment_set_variable",
+    description: string,
+  ): void => {
     server.registerTool(
       name,
       {
@@ -2860,28 +3420,97 @@ function registerVariableSetTools(
           value: z4.string().min(1).max(32768),
         },
       },
-      setVariableHandler,
+      setVariableHandler(name),
     );
   };
-  if (can("variable-sets:use")) {
+  if (can("variable-sets:list") && can("secrets:list")) {
     registerListTool(
       "variable_set_list",
-      "List variable sets with variable names and metadata (versions, timestamps). Values are write-only and never returned.",
+      "List variable sets with variable names and metadata (versions, timestamps). Plaintext values are never returned by list operations.",
     );
     registerListTool(
       "environment_list",
-      "(deprecated alias of variable_set_list) List variable sets with variable names and metadata (versions, timestamps). Values are write-only and never returned.",
+      "(deprecated alias of variable_set_list) List variable sets with variable names and metadata (versions, timestamps). Plaintext values are never returned by list operations.",
+    );
+  }
+
+  if (
+    !toolspaceMode &&
+    sessionId !== null &&
+    can("variable-sets:read") &&
+    hasLiteralPermission(grant.permissions, "secrets:read")
+  ) {
+    server.registerTool(
+      "variable_set_get_variable",
+      {
+        description:
+          "Retrieve one exact plaintext variable value. This is a dedicated high-trust read: use it only when the current task requires the configured value. The access is audited against this exact live attempt.",
+        inputSchema: {
+          variableSetId: z4.string().uuid().optional(),
+          variableSetName: z4.string().min(1).max(120).optional(),
+          name: z4.string().min(1),
+        },
+      },
+      async ({ variableSetId, variableSetName, name }) => {
+        let target: { variableSetId: string } | { variableSetName: string };
+        if (variableSetId !== undefined) {
+          if (variableSetName !== undefined) {
+            throw new Error("provide exactly one of variableSetId or variableSetName");
+          }
+          target = { variableSetId };
+        } else {
+          if (variableSetName === undefined) {
+            throw new Error("provide exactly one of variableSetId or variableSetName");
+          }
+          target = { variableSetName };
+        }
+        if (
+          ("variableSetId" in target && target.variableSetId.length === 0) ||
+          ("variableSetName" in target && target.variableSetName.trim().length === 0)
+        ) {
+          throw new Error("provide exactly one of variableSetId or variableSetName");
+        }
+        const parsedName = VariableSetVariableName.safeParse(name);
+        if (!parsedName.success) {
+          throw new Error("variable set variable names must match ^[A-Z][A-Z0-9_]*$");
+        }
+        assertAllowedVariableSetVariableName(parsedName.data);
+        const claims = preferenceAttemptClaims(grant);
+        if (!claims || claims.sessionId !== sessionId) {
+          throw new Error("Exact signed secret-read attempt authority is required.");
+        }
+        await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
+        await authorizeFirstPartySession(deps, grant, sessionId, "session.secret.read");
+        const key = requireVariableSetEncryption(deps.settings);
+        const secret = await readVariableSetSecretAtomically(deps.db, {
+          accountId: grant.accountId,
+          workspaceId: grant.workspaceId,
+          subjectId: grant.subjectId,
+          ...target,
+          name: parsedName.data,
+          actor: {
+            kind: "agent_attempt",
+            sessionId: claims.sessionId,
+            turnId: claims.turnId,
+            attemptId: claims.attemptId,
+            executionGeneration: claims.executionGeneration,
+          },
+          decrypt: (valueEncrypted) => decryptVariableSetValue(key, valueEncrypted),
+        });
+        if (!secret) throw new Error("variable set variable not found");
+        return json(secret);
+      },
     );
   }
 
-  if (can("variable-sets:manage")) {
+  if (can("variable-sets:write") && can("secrets:write")) {
     registerSetTool(
       "variable_set_set_variable",
-      "Set or rotate one variable in a variable set. Target by variableSetId, or by variableSetName (created if it does not exist). The value is encrypted at rest and injected into sandboxes of sessions the variable set is attached to; it is never readable back through any API.",
+      "Set or rotate one variable in a variable set. Target by variableSetId, or by variableSetName (created if it does not exist). The value is encrypted at rest and injected into sandboxes of sessions the variable set is attached to. Reading it requires the dedicated permissioned secret-read operation.",
     );
     registerSetTool(
       "environment_set_variable",
-      "(deprecated alias of variable_set_set_variable) Set or rotate one variable in a variable set. Target by variableSetId, or by variableSetName (created if it does not exist). The value is encrypted at rest and injected into sandboxes of sessions the variable set is attached to; it is never readable back through any API.",
+      "(deprecated alias of variable_set_set_variable) Set or rotate one variable in a variable set. Target by variableSetId, or by variableSetName (created if it does not exist). The value is encrypted at rest and injected into sandboxes of sessions the variable set is attached to. Reading it requires the dedicated permissioned secret-read operation.",
     );
   }
 }
@@ -2976,7 +3605,8 @@ function repositoryWithScheduledTaskResource(
       kind: "repository",
       uri,
       ref: repository.defaultBranch,
-      mountPath: defaultRepositoryMountPath(uri),
+      provider: "github",
+      mountPath: defaultRepositoryMountPath(uri, "github"),
       ...(repository.private
         ? {
             githubInstallationId: repository.installationId,