@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/src/feedback.ts

@@ -1,39 +1,134 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
-export const FeedbackSentiment = z.enum(["positive", "negative"]);
+export const FeedbackSentiment = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["positive", "negative"]),
+);
 export type FeedbackSentiment = z.infer<typeof FeedbackSentiment>;
 
+/** Screenshots one report may carry, and the largest one accepted. */
+export const FEEDBACK_SCREENSHOT_MAX_COUNT = 3;
+export const FEEDBACK_SCREENSHOT_MAX_BYTES = 3 * 1024 * 1024;
+export const FEEDBACK_RECENT_ERRORS_MAX = 10;
+
+export const FeedbackScreenshotContentType = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["image/jpeg", "image/png"]),
+);
+export type FeedbackScreenshotContentType = z.infer<typeof FeedbackScreenshotContentType>;
+
+/** A screenshot sent with a report: the image bytes, base64-encoded. */
+export const FeedbackScreenshotUpload = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      contentType: FeedbackScreenshotContentType,
+      base64: z
+        .string()
+        .min(1)
+        .max(Math.ceil(FEEDBACK_SCREENSHOT_MAX_BYTES / 3) * 4)
+        .regex(/^[A-Za-z0-9+/]+={0,2}$/, "Screenshot must be base64"),
+    })
+    .strict(),
+);
+export type FeedbackScreenshotUpload = z.infer<typeof FeedbackScreenshotUpload>;
+
+/** A stored screenshot. Its bytes are read separately by index. */
+export const FeedbackScreenshot = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    index: z.number().int().nonnegative(),
+    contentType: FeedbackScreenshotContentType,
+    sizeBytes: z.number().int().positive(),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+  }),
+);
+export type FeedbackScreenshot = z.infer<typeof FeedbackScreenshot>;
+
+/** An error the person saw shortly before reporting, as the app showed it. */
+export const FeedbackRecentError = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      at: z.string().datetime(),
+      title: z.string().max(200).optional(),
+      message: z.string().min(1).max(1000),
+      code: z.string().max(120).optional(),
+      status: z.number().int().min(0).max(999).optional(),
+      screen: z.string().max(500).optional(),
+    })
+    .strict(),
+);
+export type FeedbackRecentError = z.infer<typeof FeedbackRecentError>;
+
+/**
+ * Facts about the app and device a report came from, so it can be reproduced
+ * without asking. Every field but source is optional; clients send what they know.
+ */
+export const FeedbackContext = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      source: z.enum(["web", "desktop", "mobile"]),
+      /** How the person opened the report: a menu item, or shaking the phone. */
+      trigger: z.enum(["menu", "shake"]).optional(),
+      platform: z.string().max(32).optional(),
+      appVersion: z.string().max(64).optional(),
+      buildNumber: z.string().max(64).optional(),
+      osVersion: z.string().max(64).optional(),
+      deviceModel: z.string().max(120).optional(),
+      /** The screen in view, as an app path such as /session/<id>. */
+      screen: z.string().max(500).optional(),
+      locale: z.string().max(35).optional(),
+      timeZone: z.string().max(64).optional(),
+      online: z.boolean().optional(),
+      recentErrors: z.array(FeedbackRecentError).max(FEEDBACK_RECENT_ERRORS_MAX).optional(),
+    })
+    .strict(),
+);
+export type FeedbackContext = z.infer<typeof FeedbackContext>;
+
 /** A new key means a new submission; retry the same payload with the same key. */
-export const CreateFeedbackRequest = z
-  .object({
-    idempotencyKey: z.string().uuid(),
-    sessionId: z.string().uuid().optional(),
-    turnId: z.string().uuid().optional(),
-    sentiment: FeedbackSentiment.optional(),
-    comment: z.string().max(4000).optional(),
-  })
-  .strict()
-  .superRefine((value, ctx) => {
-    if (value.turnId && !value.sessionId)
-      ctx.addIssue({ code: "custom", path: ["turnId"], message: "turnId requires sessionId" });
-    if (value.sentiment && !value.sessionId)
-      ctx.addIssue({ code: "custom", path: ["sentiment"], message: "Ratings require a session" });
-    if (!value.sentiment && !value.comment?.trim())
-      ctx.addIssue({ code: "custom", path: ["comment"], message: "Provide a rating or a comment" });
-  });
+export const CreateFeedbackRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      idempotencyKey: primitives.uuid,
+      sessionId: primitives.optionalUuid,
+      turnId: primitives.optionalUuid,
+      sentiment: FeedbackSentiment.optional(),
+      comment: z.string().max(4000).optional(),
+      context: FeedbackContext.optional(),
+      screenshots: z.array(FeedbackScreenshotUpload).max(FEEDBACK_SCREENSHOT_MAX_COUNT).optional(),
+    })
+    .strict()
+    .superRefine((value, ctx) => {
+      if (value.turnId && !value.sessionId)
+        ctx.addIssue({ code: "custom", path: ["turnId"], message: "turnId requires sessionId" });
+      if (value.sentiment && !value.sessionId)
+        ctx.addIssue({ code: "custom", path: ["sentiment"], message: "Ratings require a session" });
+      if (!value.sentiment && !value.comment?.trim())
+        ctx.addIssue({
+          code: "custom",
+          path: ["comment"],
+          message: "Provide a rating or a comment",
+        });
+    }),
+);
 export type CreateFeedbackRequest = z.infer<typeof CreateFeedbackRequest>;
 
-export const Feedback = z.object({
-  id: z.string().uuid(),
-  workspaceId: z.string().uuid(),
-  subjectId: z.string(),
-  principalKind: z.string().nullable(),
-  sessionId: z.string().uuid().nullable(),
-  turnId: z.string().uuid().nullable(),
-  sentiment: FeedbackSentiment.nullable(),
-  comment: z.string().nullable(),
-  createdAt: z.string().datetime(),
-});
+export const Feedback = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    id: primitives.uuid,
+    workspaceId: primitives.uuid,
+    subjectId: primitives.string,
+    principalKind: primitives.nullableString,
+    sessionId: primitives.nullableUuid,
+    turnId: primitives.nullableUuid,
+    sentiment: FeedbackSentiment.nullable(),
+    comment: primitives.nullableString,
+    context: FeedbackContext.nullable(),
+    screenshots: z.array(FeedbackScreenshot),
+    createdAt: primitives.dateTime,
+  }),
+);
 export type Feedback = z.infer<typeof Feedback>;
-export const FeedbackSubmissionResponse = z.object({ feedback: Feedback, replayed: z.boolean() });
+export const FeedbackSubmissionResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ feedback: Feedback, replayed: primitives.boolean }),
+);
 export type FeedbackSubmissionResponse = z.infer<typeof FeedbackSubmissionResponse>;

package/src/file-access.ts

@@ -0,0 +1,26 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+import { WorkspaceArtifactVisibility } from "./artifacts";
+
+/**
+ * Who can open a file, in the same two words as a Site or a chat: only its
+ * owner ("private", shown as Only me) or everyone in the workspace.
+ * `whoCanOpen` is one plain sentence for the agent that made or shared the
+ * file, so it never sends a private link to someone who cannot open it.
+ */
+export const FileAccess = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      visibility: WorkspaceArtifactVisibility,
+      whoCanOpen: z.string().min(1).max(512),
+    })
+    .strict(),
+);
+export type FileAccess = z.infer<typeof FileAccess>;
+
+/** The owner's change of who can open one file. */
+export const UpdateFileVisibilityRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({ visibility: WorkspaceArtifactVisibility }).strict(),
+);
+export type UpdateFileVisibilityRequest = z.infer<typeof UpdateFileVisibilityRequest>;

package/src/first-party-tool-authorization.ts

@@ -0,0 +1,383 @@
+import type { FirstPartyMcpToolName } from "./index";
+import type { Permission } from "./permissions";
+
+export type FirstPartyToolAuthorization = {
+  sessionRequired?: true;
+  /**
+   * Acts as a person: registered only in a session a person started
+   * themselves (not a child or service session) when selected, or whenever
+   * the session has full access. Never carried into a child's selection.
+   */
+  personSessionRequired?: true;
+  allOf?: readonly Permission[];
+  anyOf?: readonly Permission[];
+};
+
+/**
+ * Authorization is deliberately complete and separate from visibility. The
+ * `satisfies Record` check makes every catalog addition choose an explicit
+ * registration predicate before it can compile.
+ *
+ * The API's first-party MCP server registers a tool only when this predicate
+ * passes for the attempt's grant. The worker reads the same table to know which
+ * selected tools a permission ceiling can never admit (prompt rendering only).
+ */
+export const FIRST_PARTY_TOOL_AUTHORIZATION = {
+  set_session_title: { sessionRequired: true, allOf: ["sessions:control"] },
+  notify_user: { sessionRequired: true, allOf: ["sessions:control"] },
+  notification_withdraw: { sessionRequired: true, allOf: ["sessions:control"] },
+  inbox_tidy: { sessionRequired: true, allOf: ["sessions:control"] },
+  goal_set: { sessionRequired: true, allOf: ["goals:manage"] },
+  goal_update: { sessionRequired: true, allOf: ["goals:manage"] },
+  goal_progress: { sessionRequired: true, allOf: ["goals:manage"] },
+  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"] },
+  knowledge_search: { sessionRequired: true, allOf: ["documents:search"] },
+  knowledge_prepare_save: { sessionRequired: true, allOf: ["documents:search"] },
+  knowledge_get: { sessionRequired: true, allOf: ["documents:search"] },
+  knowledge_browse: { sessionRequired: true, allOf: ["documents:search"] },
+  knowledge_retain_file: { sessionRequired: true, allOf: ["documents:search", "files:read"] },
+  // Recorded meetings, read as the person the session works for. Saving notes
+  // follows the meeting: it succeeds only on a meeting that person can see,
+  // like knowledge writes, and never needs session orchestration rights.
+  meetings_search: { sessionRequired: true, allOf: ["sessions:read"] },
+  meeting_read: { sessionRequired: true, allOf: ["sessions:read"] },
+  meeting_notes_save: { sessionRequired: true, allOf: ["sessions:read"] },
+  knowledge_retain_message: { sessionRequired: true, allOf: ["documents:search", "sessions:read"] },
+  knowledge_save: { sessionRequired: true, allOf: ["documents:search"] },
+  knowledge_archive: { sessionRequired: true, allOf: ["documents:search"] },
+  instruction_policy_save: { sessionRequired: true, allOf: ["documents:search"] },
+  instruction_policy_get: { sessionRequired: true, allOf: ["documents:search"] },
+  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_get: { sessionRequired: true, allOf: ["workspace:read"] },
+  task_notes_list: { sessionRequired: true, allOf: ["sessions:read"] },
+  task_note_save: { sessionRequired: true, allOf: ["sessions:control"] },
+  task_note_archive: { sessionRequired: true, allOf: ["sessions:control"] },
+  task_note_replace: { sessionRequired: true, allOf: ["sessions:control"] },
+  work_claim_upsert: { sessionRequired: true, allOf: ["sessions:control"] },
+  work_claim_release: { sessionRequired: true, allOf: ["sessions:control"] },
+  knowledge_propose: { sessionRequired: true, allOf: ["documents:search"] },
+  knowledge_correct: { sessionRequired: true, allOf: ["documents:search"] },
+  task_note_promote_knowledge: {
+    sessionRequired: true,
+    allOf: ["documents:search", "sessions:control"],
+  },
+  task_note_promote_instruction_policy: {
+    sessionRequired: true,
+    allOf: ["documents:search", "sessions:control", "workspace:read"],
+  },
+  task_note_promote_preference: {
+    sessionRequired: true,
+    allOf: ["documents:search", "sessions:control", "workspace:read"],
+  },
+  instruction_policy_propose: {
+    sessionRequired: true,
+    allOf: ["documents:search", "workspace:read"],
+  },
+  preference_propose: {
+    sessionRequired: true,
+    allOf: ["documents:search", "workspace:read"],
+  },
+  // Explicit user-directed remember composes task-note evidence with the
+  // governed promotion path, so it needs the union of both permission sets.
+  remember: {
+    sessionRequired: true,
+    allOf: ["documents:search", "sessions:control", "workspace:read"],
+  },
+  remember_confirm: {
+    sessionRequired: true,
+    allOf: ["documents:search", "sessions:control", "workspace:read"],
+  },
+  company_profile_propose: {
+    sessionRequired: true,
+    allOf: ["sessions:control", "workspace:read"],
+  },
+  company_profile_confirm: {
+    sessionRequired: true,
+    allOf: ["sessions:control", "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"] },
+  connected_machine_enroll_token: { allOf: ["enrollments:manage"] },
+  connected_machine_enable_screen_control: { allOf: ["enrollments:manage"] },
+  rig_list: { allOf: ["rigs:use"] },
+  rig_get: { allOf: ["rigs:use"] },
+  rig_propose_change: { allOf: ["rigs:use"] },
+  rig_verify: { allOf: ["rigs:use"] },
+  rig_promote: { allOf: ["rigs:manage"] },
+  sessions_list: { allOf: ["sessions:read"] },
+  session_get: { allOf: ["sessions:read"] },
+  session_set_model: { allOf: ["sessions:control"] },
+  session_events: { allOf: ["sessions:read"] },
+  // A bounded wait on named sessions. A live attempt also wakes for its own
+  // pending input; a sessionless caller (an operator, or a person's surface
+  // reached for a chat in another workspace) waits on the targets only.
+  session_wait: { 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_message_status: { sessionRequired: true, allOf: ["sessions:read"] },
+  session_target_get: { sessionRequired: true, allOf: ["sessions:read"] },
+  session_target_set: { sessionRequired: true, allOf: ["sessions:read", "sessions:control"] },
+  session_pause: { allOf: ["sessions:control"] },
+  session_resume: { allOf: ["sessions:control"] },
+  // A live attempt sends a typed Agent Steer; a sessionless caller appends a
+  // human/API steer, as the REST steer route does.
+  session_steer: { allOf: ["sessions:control"] },
+  // A live attempt may answer another session's structured human-input
+  // request (never a tool approval, which stays human-only).
+  session_human_input_respond: { sessionRequired: true, allOf: ["sessions:control"] },
+  set_other_session_title: { allOf: ["sessions:control"] },
+  bot_template_save: { sessionRequired: true, allOf: ["sessions:create"] },
+  interaction_discover: { sessionRequired: true, allOf: ["sessions:read"] },
+  browser_open: { sessionRequired: true, allOf: ["sessions:control"] },
+  browser_tabs: { sessionRequired: true, allOf: ["sessions:control"] },
+  browser_observe: { sessionRequired: true, allOf: ["sessions:read"] },
+  browser_read: { sessionRequired: true, allOf: ["sessions:read"] },
+  browser_screenshot: { sessionRequired: true, allOf: ["sessions:read"] },
+  browser_act: { sessionRequired: true, allOf: ["sessions:control"] },
+  browser_clipboard: { sessionRequired: true, allOf: ["sessions:read"] },
+  browser_debug: { sessionRequired: true, allOf: ["sessions:read"] },
+  browser_downloads: { sessionRequired: true, allOf: ["sessions:read"] },
+  browser_download_save: {
+    sessionRequired: true,
+    allOf: ["sessions:control", "files:upload"],
+  },
+  browser_record: {
+    sessionRequired: true,
+    allOf: ["sessions:control", "files:upload"],
+  },
+  browser_auth: { sessionRequired: true, allOf: ["sessions:control"] },
+  interaction_request_human: {
+    sessionRequired: true,
+    allOf: ["sessions:control"],
+  },
+  browser_identity: { sessionRequired: true, allOf: ["sessions:control"] },
+  browser_publish: { sessionRequired: true, allOf: ["sessions:control"] },
+  browser_lifecycle: { sessionRequired: true, allOf: ["sessions:control"] },
+  computer_open: { sessionRequired: true, allOf: ["sessions:control"] },
+  computer_targets: { sessionRequired: true, allOf: ["sessions:read"] },
+  computer_observe: { sessionRequired: true, allOf: ["sessions:read"] },
+  computer_clipboard: { sessionRequired: true, allOf: ["sessions:read"] },
+  computer_act: { sessionRequired: true, allOf: ["sessions:control"] },
+  excel_run: { sessionRequired: true, allOf: ["sessions:control"] },
+  computer_lifecycle: { sessionRequired: true, allOf: ["sessions:control"] },
+  secret_search: { sessionRequired: true, allOf: ["secrets:list"] },
+  secret_save: { sessionRequired: true, allOf: ["secrets:write"] },
+  // Plaintext read: registered only for a literal `secrets:read` grant.
+  secret_get: { sessionRequired: true, allOf: ["secrets:read"] },
+  secret_move: { sessionRequired: true, allOf: ["secrets:write"] },
+  secret_delete: { sessionRequired: true, allOf: ["secrets:write"] },
+  // Credential profiles: reading names item references (secret metadata);
+  // changing one also needs workspace:admin (workspace) or sessions:control
+  // (session), checked when the tool runs.
+  secret_profile_get: { sessionRequired: true, allOf: ["secrets:list"] },
+  secret_profile_set: { sessionRequired: true, allOf: ["secrets:write"] },
+  // Retired (RETIRED_SECRET_TOOL_NAMES): never registered; kept for stored selections.
+  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"] },
+  capability_catalog_search: {
+    sessionRequired: true,
+    allOf: ["workspace:read"],
+  },
+  capability_authorization_request: {
+    sessionRequired: true,
+    allOf: ["workspace:read"],
+  },
+  custom_mcp_setup_request: {
+    sessionRequired: true,
+    allOf: ["workspace:read"],
+  },
+  github_connect_link: { allOf: ["github:use"] },
+  github_repositories_list: { allOf: ["github:use"] },
+  social_connections_list: { allOf: ["connections:read"] },
+  social_posts_recent: { allOf: ["connections:read"] },
+  social_daily_analysis_context: { allOf: ["connections:read"] },
+  social_search_live: { allOf: ["connections:read"] },
+  social_mentions_live: { allOf: ["connections:read"] },
+  social_thread_fetch: { allOf: ["connections:read"] },
+  // Writes the social_posts store, so it takes the write scope like the REST
+  // equivalent (POST /social/posts is workspace:admin).
+  social_posts_sync: { allOf: ["connections:write"] },
+  // 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"] },
+  x_accounts_list: { allOf: ["connections:read"] },
+  x_search_live: { allOf: ["connections:read"] },
+  x_mentions_live: { allOf: ["connections:read"] },
+  x_thread_fetch: { allOf: ["connections:read"] },
+  x_posts_sync: { allOf: ["connections:write"] },
+  x_post_reply: { allOf: ["connections:write"] },
+  reddit_accounts_list: { allOf: ["connections:read"] },
+  reddit_search_live: { allOf: ["connections:read"] },
+  reddit_mentions_live: { allOf: ["connections:read"] },
+  reddit_thread_fetch: { allOf: ["connections:read"] },
+  reddit_posts_sync: { allOf: ["connections:write"] },
+  reddit_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_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"],
+  },
+  event_sources_list: {
+    anyOf: ["scheduled_tasks:manage", "scheduled_tasks:run"],
+  },
+  events_get: {
+    anyOf: ["scheduled_tasks:manage", "scheduled_tasks:run"],
+  },
+  slack_bot_list_channels: { allOf: ["connections:read"] },
+  slack_bot_search: { allOf: ["connections:read"] },
+  slack_bot_channel_history: { allOf: ["connections:read"] },
+  slack_bot_thread_replies: { allOf: ["connections:read"] },
+  slack_bot_list_users: { allOf: ["connections:read"] },
+  slack_bot_list_files: { allOf: ["connections:read"] },
+  slack_bot_file_info: { allOf: ["connections:read"] },
+  slack_bot_file_content: { allOf: ["connections:read"] },
+  slack_bot_upload_file: { sessionRequired: true, allOf: ["connections:read", "files:read"] },
+  slack_bot_post_message: { allOf: ["connections:read"] },
+  // Scheduled runs only; the destination is the task's human-chosen channel.
+  slack_bot_prepare_message: { sessionRequired: true, allOf: ["connections:read"] },
+  slack_bot_send_prepared_message: { sessionRequired: true, allOf: ["connections:read"] },
+  slack_bot_delete_message: { allOf: ["connections:read"] },
+  fiken_companies_list: { allOf: ["connections:read"] },
+  fiken_contacts_list: { allOf: ["connections:read"] },
+  fiken_products_list: { allOf: ["connections:read"] },
+  fiken_invoices_list: { allOf: ["connections:read"] },
+  fiken_invoice_get: { allOf: ["connections:read"] },
+  fiken_bank_accounts_list: { allOf: ["connections:read"] },
+  fiken_purchases_list: { allOf: ["connections:read"] },
+  fiken_sales_list: { allOf: ["connections:read"] },
+  // Writes into the workspace's real accounting ledger surface take the write
+  // scope, keeping them out of the default agent permission set.
+  fiken_contact_create: { allOf: ["connections:write"] },
+  fiken_invoice_draft_create: { allOf: ["connections:write"] },
+  atlassian_sources_list: { allOf: ["connections:read"] },
+  atlassian_search: { allOf: ["connections:read"] },
+  atlassian_get: { allOf: ["connections: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"] },
+  artifacts_archive: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  artifacts_restore: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  site_data_describe: { sessionRequired: true, allOf: ["artifacts:read"] },
+  site_data_define_collection: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  site_data_query: { sessionRequired: true, allOf: ["artifacts:read"] },
+  site_data_write: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  site_data_import: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  site_data_export: { sessionRequired: true, allOf: ["artifacts:read"] },
+  site_data_reset: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  site_files_list: { sessionRequired: true, allOf: ["artifacts:read"] },
+  site_files_upload: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  site_files_delete: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  site_publication_get: { sessionRequired: true, allOf: ["artifacts:read"] },
+  site_publication_update: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  site_publication_apply_fix: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  site_hostname_check: { sessionRequired: true, allOf: ["artifacts:read"] },
+  site_sql_inspect: { sessionRequired: true, allOf: ["artifacts:read"] },
+  site_sql_enable: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  site_sql_migrate: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  site_sql_define_query: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  site_sql_query: { sessionRequired: true, allOf: ["artifacts:read"] },
+  site_sql_run: { sessionRequired: true, allOf: ["artifacts:read"] },
+  site_sql_execute: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  site_sql_export: { sessionRequired: true, allOf: ["artifacts:read"] },
+  site_sql_import: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  site_sql_reset: { sessionRequired: true, allOf: ["artifacts:publish"] },
+  sandbox_file_publish: {
+    sessionRequired: true,
+    allOf: ["files:read", "files:upload"],
+  },
+  editable_artifact_list: { sessionRequired: true, allOf: ["artifacts:read"] },
+  editable_artifact_create: {
+    sessionRequired: true,
+    allOf: ["artifacts:publish"],
+  },
+  editable_artifact_import: {
+    sessionRequired: true,
+    allOf: ["artifacts:publish", "files:read"],
+  },
+  editable_artifact_get: { sessionRequired: true, allOf: ["artifacts:read"] },
+  editable_artifact_inspect: {
+    sessionRequired: true,
+    allOf: ["artifacts:read"],
+  },
+  editable_artifact_apply: {
+    sessionRequired: true,
+    allOf: ["artifacts:publish"],
+  },
+  editable_artifact_export: {
+    sessionRequired: true,
+    allOf: ["artifacts:read"],
+  },
+  editable_artifact_export_status: {
+    sessionRequired: true,
+    allOf: ["artifacts:read", "files:upload"],
+  },
+  project_list: { allOf: ["sessions:read"] },
+  project_get: { allOf: ["sessions:read"] },
+  project_create: { allOf: ["sessions:create"] },
+  project_update: { allOf: ["sessions:create"] },
+  project_reorder: { allOf: ["sessions:create"] },
+  project_delete: { allOf: ["sessions:create"] },
+  session_set_project: { allOf: ["sessions:control"] },
+  admin_actions_search: { sessionRequired: true, personSessionRequired: true },
+  admin_action_describe: { sessionRequired: true, personSessionRequired: true },
+  admin_action_call: { sessionRequired: true, personSessionRequired: true },
+} satisfies Record<FirstPartyMcpToolName, FirstPartyToolAuthorization>;
+
+/**
+ * The permissions a session's first-party tool selection can possibly
+ * exercise, derived from the same per-tool registration data that gates the
+ * MCP surface. A caller that only proxies REST handlers on behalf of a
+ * selection (the Codemode SDK proxy) must never hold more than this: a
+ * selection without any session_* orchestration tool cannot need
+ * sessions:create or sessions:control, so a delegated token for it must not
+ * carry them either. `anyOf` alternatives are all counted because any one of
+ * them could be the permission the selection actually holds.
+ */
+export function permissionsRequiredByFirstPartyTools(
+  tools: readonly FirstPartyMcpToolName[],
+): Permission[] {
+  const required = new Set<Permission>();
+  for (const tool of tools) {
+    const policy: FirstPartyToolAuthorization | undefined = FIRST_PARTY_TOOL_AUTHORIZATION[tool];
+    if (!policy) continue;
+    for (const permission of policy.allOf ?? []) required.add(permission);
+    for (const permission of policy.anyOf ?? []) required.add(permission);
+  }
+  return [...required];
+}