@opengeni/contracts 3.1.0-canary.1 → 3.1.2

package/src/secret-totp.ts

@@ -0,0 +1,188 @@
+/**
+ * The one TOTP implementation (RFC 6238 over RFC 4226 HOTP). Codes are
+ * computed at dispatch from a stored seed and never stored (invariant I4).
+ *
+ * HMAC uses `@noble/hashes`, which is synchronous and works in Bun, Node,
+ * browsers and React Native (no WebCrypto requirement).
+ */
+import { hmac } from "@noble/hashes/hmac";
+import { sha1 } from "@noble/hashes/sha1";
+import { sha256, sha512 } from "@noble/hashes/sha2";
+
+export interface TotpParams {
+  secretBase32: string;
+  algorithm: "SHA1" | "SHA256" | "SHA512";
+  digits: 6 | 7 | 8;
+  periodSeconds: number;
+}
+
+export type SecretClock = { now(): number; sleep(ms: number): Promise<void> };
+
+export const systemSecretClock: SecretClock = {
+  now: () => Date.now(),
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+
+/** Wait for the next window when fewer than this many ms remain (Q-33). */
+export const TOTP_MIN_REMAINING_MS = 3_000;
+
+export class TotpInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TotpInputError";
+  }
+}
+
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+/** Uppercase, strip spaces, dashes and padding. */
+export function normalizeBase32Secret(input: string): string {
+  return input.replace(/[\s-]/g, "").replace(/=+$/, "").toUpperCase();
+}
+
+export function decodeBase32(input: string): Uint8Array {
+  const normalized = normalizeBase32Secret(input);
+  if (normalized.length === 0) throw new TotpInputError("TOTP secret is empty");
+  let bits = 0;
+  let value = 0;
+  const out: number[] = [];
+  for (const character of normalized) {
+    const index = BASE32_ALPHABET.indexOf(character);
+    if (index < 0) throw new TotpInputError("TOTP secret is not valid Base32");
+    value = ((value << 5) | index) & 0xffff;
+    bits += 5;
+    if (bits >= 8) {
+      out.push((value >>> (bits - 8)) & 0xff);
+      bits -= 8;
+    }
+  }
+  if (out.length === 0) throw new TotpInputError("TOTP secret is empty");
+  return Uint8Array.from(out);
+}
+
+function parseAlgorithm(value: string | null): TotpParams["algorithm"] {
+  if (value === null) return "SHA1";
+  const normalized = value.toUpperCase().replace("-", "");
+  if (normalized === "SHA1" || normalized === "SHA256" || normalized === "SHA512") {
+    return normalized;
+  }
+  throw new TotpInputError("TOTP algorithm must be SHA1, SHA256 or SHA512");
+}
+
+function parseDigits(value: string | null): TotpParams["digits"] {
+  if (value === null) return 6;
+  if (value === "6" || value === "7" || value === "8") return Number(value) as 6 | 7 | 8;
+  throw new TotpInputError("TOTP digits must be 6, 7 or 8");
+}
+
+function parsePeriod(value: string | null): number {
+  if (value === null) return 30;
+  if (!/^\d+$/.test(value)) throw new TotpInputError("TOTP period is invalid");
+  const period = Number(value);
+  if (period < 1 || period > 300) throw new TotpInputError("TOTP period must be 1 to 300 seconds");
+  return period;
+}
+
+/**
+ * Accepts an `otpauth://totp/...` URI or a bare Base32 seed (spaces, dashes,
+ * padding and lowercase tolerated). Throws `TotpInputError`.
+ */
+export function parseTotpInput(input: string): TotpParams {
+  const trimmed = input.trim();
+  if (/^otpauth:/i.test(trimmed)) {
+    let url: URL;
+    try {
+      url = new URL(trimmed);
+    } catch {
+      throw new TotpInputError("TOTP otpauth URI is invalid");
+    }
+    // Engines differ on whether the type lands in host or pathname for
+    // non-special schemes; accept both.
+    const kind = (
+      url.hostname ||
+      url.pathname.replace(/^\/+/, "").split("/")[0] ||
+      ""
+    ).toLowerCase();
+    if (kind !== "totp") throw new TotpInputError("only otpauth://totp URIs are supported");
+    const secret = url.searchParams.get("secret");
+    if (!secret) throw new TotpInputError("TOTP otpauth URI has no secret");
+    const secretBase32 = normalizeBase32Secret(secret);
+    decodeBase32(secretBase32);
+    return {
+      secretBase32,
+      algorithm: parseAlgorithm(url.searchParams.get("algorithm")),
+      digits: parseDigits(url.searchParams.get("digits")),
+      periodSeconds: parsePeriod(url.searchParams.get("period")),
+    };
+  }
+  const secretBase32 = normalizeBase32Secret(trimmed);
+  decodeBase32(secretBase32);
+  return { secretBase32, algorithm: "SHA1", digits: 6, periodSeconds: 30 };
+}
+
+/** True when `input` parses as a TOTP seed or otpauth URI. */
+export function isValidTotpInput(input: string): boolean {
+  try {
+    parseTotpInput(input);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function hotp(key: Uint8Array, counter: number, params: TotpParams): string {
+  const message = new Uint8Array(8);
+  let remaining = counter;
+  for (let index = 7; index >= 0; index -= 1) {
+    message[index] = remaining % 256;
+    remaining = Math.floor(remaining / 256);
+  }
+  const hash = params.algorithm === "SHA1" ? sha1 : params.algorithm === "SHA256" ? sha256 : sha512;
+  const digest = hmac(hash, key, message);
+  const offset = digest[digest.length - 1]! & 0x0f;
+  const binary =
+    ((digest[offset]! & 0x7f) << 24) |
+    ((digest[offset + 1]! & 0xff) << 16) |
+    ((digest[offset + 2]! & 0xff) << 8) |
+    (digest[offset + 3]! & 0xff);
+  return String(binary % 10 ** params.digits).padStart(params.digits, "0");
+}
+
+/** Synchronous form of `totpCode` for UI rendering loops. */
+export function totpCodeSync(params: TotpParams, atMs: number): string {
+  if (!Number.isFinite(atMs) || atMs < 0) throw new TotpInputError("TOTP time is invalid");
+  if (!Number.isInteger(params.periodSeconds) || params.periodSeconds < 1) {
+    throw new TotpInputError("TOTP period is invalid");
+  }
+  const counter = Math.floor(atMs / 1000 / params.periodSeconds);
+  return hotp(decodeBase32(params.secretBase32), counter, params);
+}
+
+/** The code valid at `atMs` (Unix milliseconds). */
+export async function totpCode(params: TotpParams, atMs: number): Promise<string> {
+  return totpCodeSync(params, atMs);
+}
+
+/** Milliseconds left in the window containing `atMs`. */
+export function totpRemainingMs(params: TotpParams, atMs: number): number {
+  const periodMs = params.periodSeconds * 1000;
+  return periodMs - (atMs % periodMs);
+}
+
+/**
+ * The code to type or send right now. When fewer than 3 s remain in the
+ * current window, waits for the next window so the code is not stale on
+ * arrival (Q-33).
+ */
+export async function totpCodeAtDispatch(
+  params: TotpParams,
+  clock: SecretClock = systemSecretClock,
+): Promise<{ code: string; expiresAtMs: number }> {
+  let now = clock.now();
+  const remaining = totpRemainingMs(params, now);
+  if (remaining < TOTP_MIN_REMAINING_MS) {
+    await clock.sleep(remaining);
+    now = clock.now();
+  }
+  return { code: totpCodeSync(params, now), expiresAtMs: now + totpRemainingMs(params, now) };
+}

package/src/session-final-reply.ts

@@ -0,0 +1,16 @@
+/** A response-quality notice, not a failed turn or a completed deliverable. */
+export const EMPTY_FINAL_REPLY_NOTICE =
+  "The model returned no final reply after a reply reminder. Completed work is preserved; the goal and later updates are unaffected.";
+
+export type EmptyFinalReplyCompletion = {
+  emptyFinalReply: true;
+};
+
+export function turnCompletedWithEmptyFinalReply(payload: unknown): boolean {
+  return (
+    payload !== null &&
+    typeof payload === "object" &&
+    !Array.isArray(payload) &&
+    (payload as { emptyFinalReply?: unknown }).emptyFinalReply === true
+  );
+}

package/src/session-goal-reports.ts

@@ -0,0 +1,64 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+export const SessionGoalReportRequirement = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      id: z
+        .string()
+        .max(64)
+        .describe(
+          "Stable report requirement identifier, at most 64 ASCII characters; not a title or status.",
+        )
+        .regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/),
+      title: z
+        .string()
+        .trim()
+        .min(1)
+        .max(512)
+        .describe(
+          "Short human-readable report title, at most 512 UTF-8 bytes. Keep normal spaces; do not put the report or a progress transcript here.",
+        )
+        .refine(
+          (value) => new TextEncoder().encode(value).byteLength <= 512,
+          "Report title exceeds 512 UTF-8 bytes",
+        ),
+    })
+    .strict(),
+);
+export type SessionGoalReportRequirement = z.infer<typeof SessionGoalReportRequirement>;
+
+export const SessionGoalReportRequirements = /* @__PURE__ */ defineSchema(() =>
+  z
+    .array(SessionGoalReportRequirement)
+    .max(16)
+    .superRefine((requirements, context) => {
+      if (new Set(requirements.map((item) => item.id)).size !== requirements.length) {
+        context.addIssue({ code: "custom", message: "Duplicate report requirement IDs" });
+      }
+    }),
+);
+
+export const SessionGoalReportDelivery = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      requirementId: SessionGoalReportRequirement.shape.id,
+      artifactId: z
+        .string()
+        .regex(/^[0-9a-f]{32}$/)
+        .refine((value) => !/^0+$/.test(value)),
+      inspectionReceiptId: z.string().uuid(),
+    })
+    .strict(),
+);
+export type SessionGoalReportDelivery = z.infer<typeof SessionGoalReportDelivery>;
+export const SessionGoalReportDeliveries = /* @__PURE__ */ defineSchema(() =>
+  z
+    .array(SessionGoalReportDelivery)
+    .max(16)
+    .superRefine((deliveries, context) => {
+      if (new Set(deliveries.map((item) => item.requirementId)).size !== deliveries.length) {
+        context.addIssue({ code: "custom", message: "Duplicate report delivery requirement IDs" });
+      }
+    }),
+);

package/src/session-history-import.ts

@@ -0,0 +1,177 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+import { Session } from "./index";
+import type { SessionEventType } from "./index";
+
+/** Import is a server-side migration boundary, not an execution/history API. */
+export const SESSION_HISTORY_IMPORT_MAX_EVENTS = 100;
+export const SESSION_HISTORY_IMPORT_MAX_BODY_BYTES = 1_048_576;
+export const SESSION_HISTORY_IMPORT_MAX_EVENT_BYTES = 262_144;
+
+/** Historical facts only: no approval, credential, control or execution inputs. */
+export const ARCHIVED_SESSION_IMPORT_EVENT_TYPES = [
+  "user.message",
+  "agent.message.delta",
+  "agent.message.completed",
+  "agent.reasoning.delta",
+  "agent.toolCall.created",
+  "agent.toolCall.output",
+  "artifact.created",
+  "turn.started",
+  "turn.completed",
+  "turn.failed",
+  "turn.cancelled",
+  "turn.superseded",
+  "goal.set",
+  "goal.updated",
+  "goal.progress",
+  "goal.completed",
+  "goal.paused",
+  "goal.resumed",
+  "goal.cleared",
+] as const satisfies readonly SessionEventType[];
+
+export const SessionImportedArchive = /* @__PURE__ */ /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      importId: z.string().min(1).max(200),
+      importedAt: z.iso.datetime({ offset: true }),
+      readOnly: z.literal(true),
+    })
+    .strict(),
+);
+export type SessionImportedArchive = z.infer<typeof SessionImportedArchive>;
+
+/** JS/SQL session seams preserve millisecond precision; never silently truncate. */
+const sourceTimestamp = /* @__PURE__ */ /* @__PURE__ */ defineSchema(() =>
+  z.iso
+    .datetime({ offset: true })
+    .refine((value) => !/\.\d{4}/u.test(value), "Source timestamp supports at most milliseconds"),
+);
+
+/** Validate JSON without coercing dates, dropping undefined, or rewriting text. */
+function isImportJson(value: unknown): boolean {
+  const pending: Array<{ value: unknown; depth: number }> = [{ value, depth: 0 }];
+  const seen = new Set<object>();
+  let nodes = 0;
+  while (pending.length > 0) {
+    const entry = pending.pop()!;
+    if (++nodes > 100_000 || entry.depth > 64) return false;
+    const current = entry.value;
+    if (current === null || typeof current === "string" || typeof current === "boolean") continue;
+    if (typeof current === "number") {
+      if (!Number.isFinite(current) || Object.is(current, -0)) return false;
+      continue;
+    }
+    if (typeof current !== "object" || seen.has(current)) return false;
+    seen.add(current);
+    if (Array.isArray(current)) {
+      for (let index = 0; index < current.length; index++) {
+        if (!Object.hasOwn(current, index)) return false;
+        pending.push({ value: current[index], depth: entry.depth + 1 });
+      }
+    } else {
+      const prototype = Object.getPrototypeOf(current);
+      if (prototype !== Object.prototype && prototype !== null) return false;
+      for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(current))) {
+        if (!descriptor.enumerable || !Object.hasOwn(descriptor, "value")) return false;
+        pending.push({ value: descriptor.value, depth: entry.depth + 1 });
+      }
+      if (Object.getOwnPropertySymbols(current).length > 0) return false;
+    }
+  }
+  return true;
+}
+
+function jsonBytes(value: unknown): number {
+  try {
+    return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+  } catch {
+    return Number.POSITIVE_INFINITY;
+  }
+}
+
+export const ArchivedSessionImportEvent = /* @__PURE__ */ /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      type: z.enum(ARCHIVED_SESSION_IMPORT_EVENT_TYPES),
+      createdAt: sourceTimestamp,
+      /** Source turn identity is presentation correlation; no execution row is created. */
+      turnId: z.string().uuid().nullable().optional(),
+      payload: z
+        .record(z.string(), z.unknown())
+        .refine(isImportJson, "Payload must be bounded JSON"),
+    })
+    .strict()
+    .refine(
+      (event) => isImportJson(event) && jsonBytes(event) <= SESSION_HISTORY_IMPORT_MAX_EVENT_BYTES,
+      "Imported event exceeds its JSON or byte limit",
+    ),
+);
+export type ArchivedSessionImportEvent = z.infer<typeof ArchivedSessionImportEvent>;
+
+const importEvents = /* @__PURE__ */ /* @__PURE__ */ defineSchema(() =>
+  z.array(ArchivedSessionImportEvent).max(SESSION_HISTORY_IMPORT_MAX_EVENTS),
+);
+
+export const ImportArchivedSessionRequest = /* @__PURE__ */ /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      importId: z.string().min(1).max(200),
+      title: z.string().min(1).max(200),
+      createdAt: sourceTimestamp,
+      /** The authenticated asUser actor supplies creator/owner, never a display label. */
+      visibility: z.enum(["workspace_shared", "user_private"]).optional(),
+      events: importEvents.default([]),
+    })
+    .strict()
+    .refine(
+      (request) => jsonBytes(request) <= SESSION_HISTORY_IMPORT_MAX_BODY_BYTES,
+      "Import request exceeds its byte limit",
+    ),
+);
+export type ImportArchivedSessionRequest = z.input<typeof ImportArchivedSessionRequest>;
+
+export const AppendArchivedSessionEventsRequest = /* @__PURE__ */ /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      batchId: z.string().min(1).max(200),
+      offset: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(Number.MAX_SAFE_INTEGER)
+        .refine((value) => !Object.is(value, -0)),
+      events: importEvents.min(1),
+    })
+    .strict()
+    .refine(
+      (request) => jsonBytes(request) <= SESSION_HISTORY_IMPORT_MAX_BODY_BYTES,
+      "Import batch exceeds its byte limit",
+    ),
+);
+export type AppendArchivedSessionEventsRequest = z.infer<typeof AppendArchivedSessionEventsRequest>;
+
+// Lazy to preserve the root contracts initialization order; SDK uses types only.
+export const ImportArchivedSessionResponse = /* @__PURE__ */ /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    session: /* @__PURE__ */ z.lazy(() => Session),
+    importId: z.string(),
+    created: z.boolean(),
+    nextOffset: z.number().int().nonnegative(),
+  }),
+);
+export type ImportArchivedSessionResponse = z.infer<typeof ImportArchivedSessionResponse>;
+
+export const AppendArchivedSessionEventsResponse = /* @__PURE__ */ /* @__PURE__ */ defineSchema(
+  () =>
+    z.object({
+      sessionId: z.string().uuid(),
+      importId: z.string(),
+      nextOffset: z.number().int().nonnegative(),
+      replayed: z.boolean(),
+    }),
+);
+export type AppendArchivedSessionEventsResponse = z.infer<
+  typeof AppendArchivedSessionEventsResponse
+>;

package/src/session-list-entries.ts

@@ -0,0 +1,96 @@
+import type { Session, SessionListEntry } from "./index";
+import {
+  deriveAutomaticSessionTitlePreview,
+  deriveSessionDisplayTitle,
+  sessionTitleIsPending,
+} from "./session-titles";
+
+/** Explicit list projection. Detail/configuration remains available from getSession. */
+export type SessionListEntryInput = Omit<
+  SessionListEntry,
+  | "displayTitle"
+  | "renameSeed"
+  | "scheduledTaskId"
+  | "siteOrigin"
+  | "pinned"
+  | "pinnedAt"
+  | "pinVersion"
+  | "unread"
+  | "activelyWorking"
+  | "attentionVersion"
+  | "archived"
+  | "archivedAt"
+  | "archiveVersion"
+> &
+  Partial<
+    Pick<
+      Session,
+      | "pinned"
+      | "pinnedAt"
+      | "pinVersion"
+      | "unread"
+      | "activelyWorking"
+      | "attentionVersion"
+      | "archived"
+      | "archivedAt"
+      | "archiveVersion"
+    >
+  > &
+  Pick<Session, "metadata" | "initialMessage">;
+
+export function sessionListEntry(session: SessionListEntryInput): SessionListEntry {
+  const origin = session.metadata._opengeniSiteOrigin as
+    | { siteId?: unknown; title?: unknown }
+    | undefined;
+  const siteOrigin =
+    origin &&
+    typeof origin.siteId === "string" &&
+    /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i.test(origin.siteId) &&
+    typeof origin.title === "string"
+      ? { siteId: origin.siteId, title: origin.title }
+      : null;
+  const scheduledTaskId = session.metadata.scheduledTaskId;
+  return {
+    id: session.id,
+    workspaceId: session.workspaceId,
+    accountId: session.accountId,
+    status: session.status,
+    backgroundCommandActivity: session.backgroundCommandActivity,
+    hasSchedules: session.hasSchedules,
+    title: session.title,
+    titleSource: session.titleSource,
+    displayTitle: deriveSessionDisplayTitle(session),
+    renameSeed: sessionTitleIsPending(session)
+      ? (deriveAutomaticSessionTitlePreview(session.initialMessage) ?? "")
+      : (session.title?.trim() ?? ""),
+    scheduledTaskId:
+      typeof scheduledTaskId === "string" && scheduledTaskId.length > 0 ? scheduledTaskId : null,
+    siteOrigin,
+    ...(session.model ? { model: session.model } : {}),
+    ...(session.reasoningEffort ? { reasoningEffort: session.reasoningEffort } : {}),
+    createdBy: session.createdBy,
+    channelId: session.channelId,
+    parentSessionId: session.parentSessionId,
+    rootSessionId: session.rootSessionId,
+    effectiveControl: session.effectiveControl,
+    inputWait: session.inputWait,
+    lastSequence: session.lastSequence,
+    pinned: session.pinned ?? false,
+    pinnedAt: session.pinnedAt ?? null,
+    pinVersion: session.pinVersion ?? 0,
+    unread: session.unread ?? false,
+    activelyWorking: session.activelyWorking ?? false,
+    attentionVersion: session.attentionVersion ?? 0,
+    archived: session.archived ?? false,
+    archivedAt: session.archivedAt ?? null,
+    importedArchive: session.importedArchive,
+    ...(session.retention ? { retention: session.retention } : {}),
+    archiveVersion: session.archiveVersion ?? 0,
+    treeStats: session.treeStats,
+    requiresActionSince: session.requiresActionSince,
+    // Lets lists tell a runtime-held session apart from one waiting on a person.
+    ...(session.admissionBlock !== undefined ? { admissionBlock: session.admissionBlock } : {}),
+    createdAt: session.createdAt,
+    updatedAt: session.updatedAt,
+  };
+}

package/src/session-mcp-projections.ts

@@ -209,6 +209,17 @@ export function compactSessionMcpDetail(
     ...(session.parentSessionId ? { parentSessionId: session.parentSessionId } : {}),
     ...(session.activeTurnId ? { activeTurnId: session.activeTurnId } : {}),
     lastSequence: session.lastSequence,
+    // Archived sessions keep a readable timeline but accept no new work.
+    ...(session.retention?.archive
+      ? {
+          archive: {
+            state: session.retention.archive.state,
+            archivedAt: session.retention.archive.archivedAt,
+            readOnly: true,
+          },
+        }
+      : {}),
+    ...(session.retention?.keepLive ? { keepLive: true } : {}),
     ...(goal
       ? {
           goal: {

package/src/session-mcp-tool-permissions.ts

@@ -0,0 +1,108 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+import { ConnectorToolPermission } from "./connector-tool-permissions";
+import { MCP_MAX_CATALOG_TOOL_ENTRIES } from "./mcp-catalog-limits";
+
+/**
+ * Tool `_meta` key an MCP server sets in `tools/list` to recommend a default
+ * permission for that tool: `"ask"` or `"allow"`. Like `requireApproval`, it
+ * applies only when the workspace has no saved choice for the tool and no
+ * server default. The tool asks when either this or `requireApproval` says so.
+ */
+export const MCP_TOOL_RECOMMENDED_PERMISSION_META_KEY = "opengeni/recommendedPermission" as const;
+
+/** True when a listed MCP tool recommends Ask through its `_meta`. */
+export function mcpToolRecommendsApproval(tool: object): boolean {
+  const meta = (tool as { _meta?: unknown })._meta;
+  return (
+    typeof meta === "object" &&
+    meta !== null &&
+    (meta as Record<string, unknown>)[MCP_TOOL_RECOMMENDED_PERMISSION_META_KEY] === "ask"
+  );
+}
+
+// Host-attached session MCP servers have no catalog capability. Their tool
+// permissions are keyed by the same secret-free identity the runtime derives:
+// `session-mcp:<serverId>:<sha256(exact url)>`. The host names the server and
+// the exact URL it attaches to sessions; Opengeni stores and enforces the rules.
+const sessionMcpServerId = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .min(1)
+    .max(200)
+    .regex(/^[A-Za-z0-9_-]+$/),
+);
+const sessionMcpServerUrl = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .min(1)
+    .max(2048)
+    .refine(
+      (value) => {
+        try {
+          const url = new URL(value);
+          return url.protocol === "https:" || url.protocol === "http:";
+        } catch {
+          return false;
+        }
+      },
+      { message: "url must be the exact http(s) URL attached to sessions" },
+    ),
+);
+const exactToolName = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .min(1)
+    .max(512)
+    .refine((name) => name !== "*" && name === name.trim(), {
+      message: "Tool names must be exact and cannot use the server-default wildcard.",
+    }),
+);
+
+export const SessionMcpToolPermissionsQuery = /* @__PURE__ */ defineSchema(() =>
+  z.object({ serverId: sessionMcpServerId, url: sessionMcpServerUrl }).strict(),
+);
+export type SessionMcpToolPermissionsQuery = z.infer<typeof SessionMcpToolPermissionsQuery>;
+
+/** Saved choices only. Tools without a rule follow `defaultPermission`, then
+ * the server's recommendation (the tool's `opengeni/recommendedPermission`
+ * `_meta`, or the attaching session's `requireApproval`), then Allow. */
+export const SessionMcpToolPermissionsResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    connectionId: z.string(),
+    serverId: z.string(),
+    defaultPermission: ConnectorToolPermission.nullable(),
+    tools: z.array(z.object({ toolName: z.string(), permission: ConnectorToolPermission })),
+    revision: z.string(),
+    canManage: z.boolean(),
+    appliesTo: z.literal("next_attempt"),
+  }),
+);
+export type SessionMcpToolPermissionsResponse = z.infer<typeof SessionMcpToolPermissionsResponse>;
+
+export const UpdateSessionMcpToolPermissionsRequest = /* @__PURE__ */ defineSchema(() =>
+  z.discriminatedUnion("target", [
+    z
+      .object({
+        serverId: sessionMcpServerId,
+        url: sessionMcpServerUrl,
+        target: z.literal("default"),
+        permission: ConnectorToolPermission.nullable(),
+        expectedRevision: z.string().optional(),
+      })
+      .strict(),
+    z
+      .object({
+        serverId: sessionMcpServerId,
+        url: sessionMcpServerUrl,
+        target: z.literal("tools"),
+        toolNames: z.array(exactToolName).min(1).max(MCP_MAX_CATALOG_TOOL_ENTRIES),
+        permission: ConnectorToolPermission.nullable(),
+        expectedRevision: z.string().optional(),
+      })
+      .strict(),
+  ]),
+);
+export type UpdateSessionMcpToolPermissionsRequest = z.infer<
+  typeof UpdateSessionMcpToolPermissionsRequest
+>;