@ganju/utils 0.0.14 → 0.0.16

package/src/schema.ts

@@ -3,9 +3,27 @@ import { z } from 'zod';
 import { constants } from './constants';
 import { isAllowedLlmBaseUrl, requiresLlmBaseUrl } from './llmBaseUrl';
 import { isReservedSlug, isValidSlugFormat } from './slug';
+import { isBlockedUrl } from './ssrf';
 import { isReservedToolName } from './reservedToolName';
 import { slugifyTitle } from './slugifyTitle';
 import { TOOL_EFFECTS } from './toolConfirmation';
+import {
+  PARTICIPANT_DAILY_LIMIT_MAX,
+  PARTICIPANT_DAILY_LIMIT_OFF
+} from './channelCustomer';
+import {
+  DATA_ACCESS_LEVELS,
+  DATA_COLUMN_TYPES,
+  DATA_MAX_COLUMNS,
+  DATA_MAX_DESCRIPTION,
+  DATA_MAX_ENUM_VALUES,
+  DATA_MAX_INSERT_ROWS,
+  DATA_MAX_LABEL,
+  DATA_IMPACT_MAX_IDS,
+  DATA_MAX_PAGE,
+  DATA_MAX_WRITE_OPERATIONS,
+  DATA_ON_DELETE
+} from './dataTypes';
 
 // A prompt title becomes a slash command; it must not collide with a command
 // the channel runner handles itself (e.g. `/link`).
@@ -181,6 +199,15 @@ const INVITATION_RESPOND = z.object({
   action: z.enum(constants.INVITATION_RESPONSES)
 });
 
+const TOOL_APPROVAL_GET = z.object({
+  approvalId: z.uuid()
+});
+
+const TOOL_APPROVAL_DECIDE = z.object({
+  approvalId: z.uuid(),
+  decision: z.enum(constants.TOOL_APPROVAL_DECISIONS)
+});
+
 const INVITATION_GET_BY_TOKEN = z.object({
   token: z.string().min(8).max(128)
 });
@@ -279,6 +306,10 @@ const ARTIFACT_CREATE_WEBSITE_VIEW = z.object({
     .refine(
       v => /^https?:\/\//i.test(v),
       'Only http and https URLs are supported'
+    )
+    .refine(
+      v => !isBlockedUrl(v),
+      "This address points to a private network and can't be crawled"
     ),
   description: z.string().optional(),
   maxPages: z.number().int().min(1).max(constants.CRAWL_MAX_PAGES_LIMIT),
@@ -292,6 +323,10 @@ const ARTIFACT_CREATE_WEBSITE = z.object({
     .refine(
       v => /^https?:\/\//i.test(v),
       'Only http and https URLs are supported'
+    )
+    .refine(
+      v => !isBlockedUrl(v),
+      "This address points to a private network and can't be crawled"
     ),
   description: z.string().optional(),
   crawlConfig: z.object({
@@ -489,6 +524,214 @@ const ARTIFACT_REMOVE_RESOURCE = z.object({
   organizationId: z.uuid()
 });
 
+const DATA_DATABASE_GET = z.object({
+  projectId: z.uuid(),
+  userId: z.uuid(),
+  organizationId: z.uuid()
+});
+
+// The name is what the owner types to delete it; it defaults to the
+// project's slug. `replaceDeleted` starts over while a deleted database is
+// still in its grace period, giving up the chance to restore it.
+const DATA_DATABASE_CREATE = DATA_DATABASE_GET.extend({
+  name: z.string().trim().min(1).max(100).optional(),
+  replaceDeleted: z.boolean().optional()
+});
+
+const DATA_DATABASE_DELETE = DATA_DATABASE_GET.extend({
+  confirmName: z.string().min(1)
+});
+
+// The bodies and query strings of the Data API. Each one is what a client
+// sends; the route schemas below add the path's ids. The database object
+// checks every rule again (names, types, relations), so these describe the
+// shape and leave the meaning to it.
+const DATA_IDENTIFIER = z.string().min(1).max(63);
+const DATA_DEFAULT_VALUE = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null()
+]);
+const DATA_TEXT = (max: number) => z.string().max(max).nullable().optional();
+
+const DATA_COLUMN_INPUT = z.strictObject({
+  name: DATA_IDENTIFIER,
+  type: z.enum(DATA_COLUMN_TYPES),
+  label: DATA_TEXT(DATA_MAX_LABEL),
+  description: DATA_TEXT(DATA_MAX_DESCRIPTION),
+  required: z.boolean().optional(),
+  unique: z.boolean().optional(),
+  filterable: z.boolean().optional(),
+  searchable: z.boolean().optional(),
+  personal: z.boolean().optional(),
+  values: z.array(z.string().min(1)).max(DATA_MAX_ENUM_VALUES).optional(),
+  table: DATA_IDENTIFIER.optional(),
+  onDelete: z.enum(DATA_ON_DELETE).optional(),
+  min: z.number().nullable().optional(),
+  default: DATA_DEFAULT_VALUE.optional()
+});
+
+// The CLI's schema file holds a list of these.
+const DATA_TABLE_INPUT = z.strictObject({
+  name: DATA_IDENTIFIER,
+  label: DATA_TEXT(DATA_MAX_LABEL),
+  description: DATA_TEXT(DATA_MAX_DESCRIPTION),
+  displayColumn: DATA_IDENTIFIER.nullable().optional(),
+  access: z.enum(DATA_ACCESS_LEVELS).optional(),
+  customerScoped: z.boolean().optional(),
+  history: z.boolean().optional(),
+  columns: z.array(DATA_COLUMN_INPUT).max(DATA_MAX_COLUMNS)
+});
+
+const DATA_TABLE_PATCH = DATA_TABLE_INPUT.omit({ columns: true }).partial();
+
+// A null puts the setting back to its default.
+const DATA_COLUMN_PATCH = DATA_COLUMN_INPUT.partial();
+
+const DATA_TABLE_DROP_BODY = z.strictObject({ confirmName: z.string().min(1) });
+
+const DATA_ROW_VALUES = z.record(z.string(), z.unknown());
+
+// A JSON value carried in a query string, e.g. `where={"status":"open"}`.
+const DATA_JSON_PARAM = z.string().transform((text, ctx) => {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    ctx.addIssue({
+      code: 'custom',
+      message: 'This is JSON, e.g. {"status":"open"}'
+    });
+    return z.NEVER;
+  }
+});
+
+// A comma-separated list in a query string: `sort=-created_at,name`.
+const DATA_LIST_PARAM = z.string().transform(text =>
+  text
+    .split(',')
+    .map(item => item.trim())
+    .filter(Boolean)
+);
+
+const DATA_ROW_LIST_QUERY = z.strictObject({
+  where: DATA_JSON_PARAM.optional(),
+  sort: DATA_LIST_PARAM.optional(),
+  include: DATA_LIST_PARAM.optional(),
+  limit: z.coerce.number().int().min(1).max(DATA_MAX_PAGE).optional(),
+  cursor: z.string().max(2000).optional(),
+  q: z.string().max(500).optional(),
+  timeZone: z.string().max(64).optional()
+});
+
+const DATA_ROW_GET_QUERY = DATA_ROW_LIST_QUERY.pick({
+  include: true,
+  timeZone: true
+});
+
+const DATA_ROW_CREATE_BODY = z.union([
+  z.strictObject({ values: DATA_ROW_VALUES }),
+  z.strictObject({
+    rows: z.array(DATA_ROW_VALUES).min(1).max(DATA_MAX_INSERT_ROWS)
+  })
+]);
+
+const DATA_ROW_VERSION = z.number().int().min(1);
+
+// `set` takes values, or relative changes such as { "stock": { "decrement": 2 } }.
+const DATA_ROW_UPDATE_BODY = z.strictObject({
+  set: DATA_ROW_VALUES,
+  version: DATA_ROW_VERSION.optional()
+});
+
+const DATA_ROW_DELETE_BODY = z.strictObject({
+  version: DATA_ROW_VERSION.optional()
+});
+
+const DATA_ROW_ID = z.coerce.number().int().min(1);
+
+// Without `ids`, every row of the table.
+const DATA_DELETE_PREVIEW_BODY = z.strictObject({
+  ids: z.array(z.number().int().min(1)).min(1).max(DATA_IMPACT_MAX_IDS).optional()
+});
+
+const DATA_WRITE_TARGET = {
+  table: DATA_IDENTIFIER,
+  id: z
+    .union([
+      z.number().int().min(1),
+      z.strictObject({ $ref: z.number().int().min(0) })
+    ])
+    .optional(),
+  where: z.record(z.string(), z.unknown()).optional(),
+  expect: z.number().int().min(0).optional(),
+  version: DATA_ROW_VERSION.optional()
+};
+
+// Applied together or not at all. A later step can use an earlier insert's
+// id as { "$ref": <step> }.
+const DATA_WRITE_OPERATION = z.discriminatedUnion('op', [
+  z.strictObject({
+    op: z.literal('insert'),
+    table: DATA_IDENTIFIER,
+    values: DATA_ROW_VALUES.optional(),
+    rows: z.array(DATA_ROW_VALUES).min(1).max(DATA_MAX_INSERT_ROWS).optional()
+  }),
+  z.strictObject({
+    op: z.literal('update'),
+    ...DATA_WRITE_TARGET,
+    set: DATA_ROW_VALUES
+  }),
+  z.strictObject({ op: z.literal('delete'), ...DATA_WRITE_TARGET })
+]);
+
+const DATA_WRITE_BODY = z.strictObject({
+  operations: z
+    .array(DATA_WRITE_OPERATION)
+    .min(1)
+    .max(DATA_MAX_WRITE_OPERATIONS)
+});
+
+const DATA_ROW_HISTORY_QUERY = z.strictObject({
+  limit: z.coerce.number().int().min(1).max(100).optional(),
+  cursor: z.coerce.number().int().min(1).optional(),
+  timeZone: z.string().max(64).optional()
+});
+
+// A time within the last 30 days, or a bookmark this API handed out (a drop,
+// a type change, or the restore to undo).
+const DATA_RESTORE_POINT_BODY = z.union([
+  z.strictObject({
+    timestamp: z.union([z.iso.datetime({ offset: true }), z.number().int()])
+  }),
+  z.strictObject({ bookmark: z.string().min(1).max(200) })
+]);
+
+const DATA_EXPORT_BODY = z.strictObject({
+  format: z.enum(['jsonl', 'csv']).optional()
+});
+
+const DATA_EXPORT_QUERY = z.strictObject({
+  exportId: z.uuid().optional()
+});
+
+// Without `table`, the export's schema.json.
+const DATA_EXPORT_FILE_QUERY = z.strictObject({
+  exportId: z.uuid(),
+  table: DATA_IDENTIFIER.optional()
+});
+
+const DATA_CHANGE_LIST_QUERY = z.strictObject({
+  limit: z.coerce.number().int().min(1).max(100).optional(),
+  cursor: z.uuid().optional()
+});
+
+const DATA_TABLE_PARAMS = DATA_DATABASE_GET.extend({ table: DATA_IDENTIFIER });
+const DATA_COLUMN_PARAMS = DATA_TABLE_PARAMS.extend({
+  column: DATA_IDENTIFIER
+});
+const DATA_ROW_PARAMS = DATA_TABLE_PARAMS.extend({ id: DATA_ROW_ID });
+
 const ARTIFACT_UPLOAD_RESOURCE_FILE = z.object({
   resourceId: z.uuid(),
   projectId: z.uuid(),
@@ -722,11 +965,11 @@ const ORGANIZATION_UPDATE_LLM_VIEW = refineUpdateBaseUrl(
   })
 );
 
-// `channel.config` is an open bag, so this stays loose — it only pins down the
-// keys we actually read, and passes everything else through untouched.
+// The channel settings an owner can write. Strict: a typo or a setting that
+// no longer exists is refused rather than stored, where nothing would read it.
 // `debounceMs` is how long a burst from one participant is buffered before the
 // agent answers it as a single turn; 0 disables buffering.
-const CHANNEL_CONFIG = z.looseObject({
+const CHANNEL_CONFIG = z.strictObject({
   debounceMs: z
     .number()
     .int()
@@ -737,7 +980,16 @@ const CHANNEL_CONFIG = z.looseObject({
           value <= constants.CHANNEL_DEBOUNCE_MAX_MS),
       `debounceMs must be 0 (disabled) or between ${constants.CHANNEL_DEBOUNCE_MIN_MS} and ${constants.CHANNEL_DEBOUNCE_MAX_MS} ms`
     )
-    .optional()
+    .optional(),
+  // Replies one customer gets in 24 hours; 0 turns the limit off.
+  participantDailyLimit: z
+    .number()
+    .int()
+    .min(PARTICIPANT_DAILY_LIMIT_OFF)
+    .max(PARTICIPANT_DAILY_LIMIT_MAX)
+    .optional(),
+  // Remember each customer's name, address, allergies and dates.
+  participantMemory: z.boolean().optional()
 });
 
 const CHANNEL_CREATE = z.object({
@@ -754,6 +1006,9 @@ const CHANNEL_UPDATE = z.object({
   channelId: z.uuid(),
   status: z.enum(constants.CHANNEL_STATUS).optional(),
   config: CHANNEL_CONFIG.optional(),
+  // Keys to change on the stored config, merged by the database, so two
+  // settings saved at once don't overwrite each other.
+  configPatch: CHANNEL_CONFIG.optional(),
   credentials: z.record(z.string(), z.string()).optional(),
   llmId: z.uuid().nullable().optional(),
   projectId: z.uuid(),
@@ -975,6 +1230,15 @@ const MCP_PROXY_CONFIG = z.object({
   allowedResources: z.array(z.string().min(1).max(2048)).max(500).optional(),
   allowedPrompts: z.array(z.string().min(1).max(256)).max(500).optional(),
   auth: MCP_PROXY_AUTH.default({ kind: constants.MCP_PROXY_AUTH_KIND_NONE }),
+  // Whether the remote's own readOnlyHint / destructiveHint decide which of its
+  // tools are confirmed. Off (or absent), every proxied tool counts as
+  // sensitive unless the owner marked it below: a server that labels its
+  // delete "read-only" would otherwise skip the question.
+  trustAnnotations: z.boolean().optional(),
+  // Remote tool names the owner marked as only reading. Read-only whatever the
+  // remote says, trusted or not. Left optional rather than defaulted, so a
+  // save that doesn't mention it keeps the stored marks.
+  readOnlyTools: z.array(z.string().min(1).max(256)).max(500).optional(),
   timeoutMs: z
     .number()
     .int()
@@ -1247,6 +1511,53 @@ const ARTIFACT_CUSTOM_CODE_LIST_LOGS = z.object({
   organizationId: z.uuid()
 });
 
+// Tool observability on the project home: per-tool health over a window.
+const PROJECT_TOOL_HEALTH = z.object({
+  days: z.coerce
+    .number()
+    .int()
+    .refine(days => constants.OBSERVABILITY_RANGE_DAYS.includes(days), {
+      message: 'Range is not valid'
+    })
+    .default(7),
+  projectId: z.uuid(),
+  userId: z.uuid(),
+  organizationId: z.uuid()
+});
+
+// The calls behind a row of that table, newest first. Paged by the id of the
+// last call shown, not its time: calls written in one insert share a
+// timestamp, and the client only sees it to the millisecond.
+const PROJECT_TOOL_CALLS = z.object({
+  tool: z.string().min(1).max(256).optional(),
+  status: z.enum(['all', 'error']).default('all'),
+  limit: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .max(constants.OBSERVABILITY_CALLS_MAX_LIMIT)
+    .default(constants.OBSERVABILITY_CALLS_DEFAULT_LIMIT),
+  after: z.uuid().optional(),
+  projectId: z.uuid(),
+  userId: z.uuid(),
+  organizationId: z.uuid()
+});
+
+// One recorded call, whole, and the session timeline it belongs to.
+const PROJECT_TOOL_CALL = z.object({
+  requestId: z.uuid(),
+  projectId: z.uuid(),
+  userId: z.uuid(),
+  organizationId: z.uuid()
+});
+
+const PROJECT_MCP_SESSION = z.object({
+  sessionId: z.uuid(),
+  projectId: z.uuid(),
+  userId: z.uuid(),
+  organizationId: z.uuid()
+});
+
 // Reads the artifact's version history and which one is currently active.
 const ARTIFACT_CUSTOM_CODE_LIST_VERSIONS = z.object({
   projectId: z.uuid(),
@@ -1609,6 +1920,8 @@ export const Schema = {
   PROJECT_INVITATION_REMOVE,
   INVITATION_RESPOND,
   INVITATION_GET_BY_TOKEN,
+  TOOL_APPROVAL_GET,
+  TOOL_APPROVAL_DECIDE,
   ORGANIZATION_MEMBER_LIST,
   ORGANIZATION_MEMBER_REMOVE,
   PROJECT_MEMBER_LIST,
@@ -1635,6 +1948,31 @@ export const Schema = {
   ARTIFACT_UPDATE_RESOURCE_VIEW,
   ARTIFACT_GET_RESOURCE,
   ARTIFACT_GET_RESOURCE_BY_ID,
+  DATA_DATABASE_GET,
+  DATA_DATABASE_CREATE,
+  DATA_DATABASE_DELETE,
+  DATA_COLUMN_INPUT,
+  DATA_TABLE_INPUT,
+  DATA_TABLE_PATCH,
+  DATA_COLUMN_PATCH,
+  DATA_TABLE_DROP_BODY,
+  DATA_ROW_LIST_QUERY,
+  DATA_ROW_GET_QUERY,
+  DATA_ROW_CREATE_BODY,
+  DATA_ROW_UPDATE_BODY,
+  DATA_ROW_DELETE_BODY,
+  DATA_DELETE_PREVIEW_BODY,
+  DATA_WRITE_OPERATION,
+  DATA_WRITE_BODY,
+  DATA_ROW_HISTORY_QUERY,
+  DATA_RESTORE_POINT_BODY,
+  DATA_EXPORT_BODY,
+  DATA_EXPORT_QUERY,
+  DATA_EXPORT_FILE_QUERY,
+  DATA_CHANGE_LIST_QUERY,
+  DATA_TABLE_PARAMS,
+  DATA_COLUMN_PARAMS,
+  DATA_ROW_PARAMS,
   ARTIFACT_REMOVE_RESOURCE,
   ARTIFACT_UPLOAD_RESOURCE_FILE,
   ARTIFACT_DOWNLOAD_RESOURCE_FILE,
@@ -1688,6 +2026,10 @@ export const Schema = {
   ARTIFACT_CUSTOM_CODE_ROLLBACK,
   ARTIFACT_CUSTOM_CODE_LIST_LOGS,
   ARTIFACT_CUSTOM_CODE_LIST_VERSIONS,
+  PROJECT_TOOL_HEALTH,
+  PROJECT_TOOL_CALLS,
+  PROJECT_TOOL_CALL,
+  PROJECT_MCP_SESSION,
   CUSTOM_CODE_INVOKE_REQUEST,
   CUSTOM_CODE_INVOKE_RESPONSE,
   CUSTOM_CODE_BROKER_CONNECTION,

package/src/ssrf.ts

@@ -1,5 +1,5 @@
 // Literal-host SSRF screening shared by the proxied tool dispatchers
-// (http-endpoint, mcp-proxy). The Workers runtime can't resolve DNS, so we can
+// (http-endpoint, mcp-proxy) and the website crawler. The Workers runtime can't resolve DNS, so we can
 // only screen literal hosts and IPs (not DNS rebinding). Private/loopback/
 // link-local ranges are always rejected; callers may further narrow with an
 // allowlist.
@@ -13,22 +13,51 @@ export const ipv4InPrivateRange = (host: string): boolean => {
   if (a === 169 && b === 254) return true; // link-local (incl. cloud metadata)
   if (a === 192 && b === 168) return true; // private
   if (a === 172 && b >= 16 && b <= 31) return true; // private
+  if (a === 100 && b >= 64 && b <= 127) return true; // carrier-grade NAT
   return false;
 };
 
+// The IPv4 address an IPv4-mapped IPv6 literal reaches. URL parsing rewrites
+// `[::ffff:127.0.0.1]` to `[::ffff:7f00:1]`, so both spellings are read.
+const mappedIpv4 = (host: string): string | null => {
+  if (!host.startsWith('::ffff:')) return null;
+  const rest = host.slice('::ffff:'.length);
+  if (rest.includes('.')) return rest;
+  const match = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(rest);
+  if (!match) return null;
+  const hi = Number.parseInt(match[1], 16);
+  const lo = Number.parseInt(match[2], 16);
+  return [hi >> 8, hi & 0xff, lo >> 8, lo & 0xff].join('.');
+};
+
 export const isBlockedHost = (hostname: string): boolean => {
-  const host = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  const host = hostname
+    .toLowerCase()
+    .replace(/^\[|\]$/g, '')
+    .replace(/\.$/, '');
   if (!host) return true;
   if (host === 'localhost' || host.endsWith('.localhost')) return true;
-  if (host === '::1' || host === '::') return true;
-  // IPv6 link-local (fe80::/10) and unique-local (fc00::/7).
-  if (
-    host.startsWith('fe80:') ||
-    host.startsWith('fc') ||
-    host.startsWith('fd')
-  ) {
+  if (host.includes(':')) {
+    // An IPv6 literal. Its prefixes are only checked here: a domain name such
+    // as fdic.gov or fcbarcelona.com starts with the same letters.
+    if (host === '::1' || host === '::') return true;
+    // Link-local (fe80::/10) and unique-local (fc00::/7).
+    if (/^fe[89ab]/.test(host) || /^f[cd]/.test(host)) return true;
+    const mapped = mappedIpv4(host);
+    return mapped !== null && ipv4InPrivateRange(mapped);
+  }
+  return ipv4InPrivateRange(host);
+};
+
+// Whether a URL may not be fetched on a user's behalf: not http(s), not a URL
+// at all, or pointing at a private, loopback or link-local host.
+export const isBlockedUrl = (url: string): boolean => {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
     return true;
   }
-  if (ipv4InPrivateRange(host)) return true;
-  return false;
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return true;
+  return isBlockedHost(parsed.hostname);
 };

package/src/toolConfirmation.ts

@@ -274,6 +274,94 @@ export const isSensitiveTool = (
 ): boolean =>
   annotations?.readOnlyHint !== true && annotations?.destructiveHint !== false;
 
+// How far a proxied tool's own hints are believed, from its install's config:
+// the remote's read-only / destructive hints only when the owner chose to
+// trust that server, and the owner's own "only reads" mark on a tool always.
+export interface ProxiedToolTrust {
+  trustHints: boolean;
+  readOnly: boolean;
+}
+
+export const proxiedToolTrust = (
+  config:
+    | { trustAnnotations?: unknown; readOnlyTools?: unknown }
+    | null
+    | undefined,
+  remoteToolName: string
+): ProxiedToolTrust => ({
+  trustHints: config?.trustAnnotations === true,
+  readOnly:
+    Array.isArray(config?.readOnlyTools) &&
+    config.readOnlyTools.includes(remoteToolName)
+});
+
+/**
+ * The annotations a proxied tool is registered with. A remote server's hints
+ * are its own claim about itself, and one that marks a delete read-only would
+ * skip every confirmation — so unless the organization chose to trust that
+ * server, the read-only and destructive hints are dropped and the tool reads
+ * as sensitive by the defaults above. A tool the owner marked as only reading
+ * is read-only whatever the remote says, trusted or not. Clients see the
+ * same, so they ask about the same tools. The harmless parts (title,
+ * openWorldHint, idempotentHint) pass through.
+ */
+export const proxiedToolAnnotations = <
+  T extends { readOnlyHint?: boolean; destructiveHint?: boolean }
+>(
+  annotations: T | null | undefined,
+  trust: ProxiedToolTrust
+): Partial<T> | undefined => {
+  const result = { ...annotations } as Partial<T>;
+  if (trust.readOnly) {
+    delete result.destructiveHint;
+    return { ...result, readOnlyHint: true };
+  }
+  if (!trust.trustHints) {
+    delete result.readOnlyHint;
+    delete result.destructiveHint;
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+};
+
+// The install-config keys that hold the owner's trust marks above.
+const PROXIED_TOOL_MARK_KEYS = ['trustAnnotations', 'readOnlyTools'] as const;
+
+/**
+ * An install's new config with the owner's trust marks carried over from the
+ * stored one wherever the new one doesn't say. A save that only knew about
+ * the allow-lists (an older dashboard, a script) must not quietly turn the
+ * marks off; one that sends them, even as false or empty, decides.
+ */
+export const keepProxiedToolMarks = (
+  stored: unknown,
+  incoming: unknown
+): unknown => {
+  if (
+    !stored ||
+    typeof stored !== 'object' ||
+    !incoming ||
+    typeof incoming !== 'object'
+  ) {
+    return incoming;
+  }
+  const merged = { ...(incoming as Record<string, unknown>) };
+  for (const key of PROXIED_TOOL_MARK_KEYS) {
+    if (merged[key] === undefined && key in stored) {
+      merged[key] = (stored as Record<string, unknown>)[key];
+    }
+  }
+  return merged;
+};
+
+/** Whether a proxied tool is confirmed, decided as its registration is. */
+export const isSensitiveProxiedTool = (
+  annotations:
+    | { readOnlyHint?: boolean; destructiveHint?: boolean }
+    | null
+    | undefined,
+  trust: ProxiedToolTrust
+): boolean => isSensitiveTool(proxiedToolAnnotations(annotations, trust));
+
 // JSON with keys sorted at every depth, so two argument objects that say the
 // same thing serialize the same whatever order the model emitted them in.
 export const stableJson = (value: unknown): string => {
@@ -289,3 +377,38 @@ export const stableJson = (value: unknown): string => {
   }
   return JSON.stringify(value) ?? 'null';
 };
+
+export type ToolApprovalStatus =
+  | 'pending'
+  | 'approved'
+  | 'denied'
+  | 'used'
+  | 'expired';
+
+/**
+ * Where an approval stands. Spent and refused come first, since an answer
+ * stays the answer after the window closes; past its time, one never answered
+ * or never used can no longer be.
+ */
+export const toolApprovalStatus = (
+  approval: {
+    expiresAt: Date;
+    approvedAt: Date | null;
+    deniedAt: Date | null;
+    usedAt: Date | null;
+  },
+  now: number = Date.now()
+): ToolApprovalStatus => {
+  if (approval.usedAt) return 'used';
+  if (approval.deniedAt) return 'denied';
+  if (approval.expiresAt.getTime() <= now) return 'expired';
+  return approval.approvedAt ? 'approved' : 'pending';
+};
+
+/** The dashboard page where the user answers one approval. */
+export const toolApprovalUrl = (
+  webUrl: string,
+  path: string,
+  approvalId: string
+): string =>
+  `${webUrl.replace(/\/+$/, '')}${path}/${encodeURIComponent(approvalId)}`;

package/src/toolCount.ts

@@ -0,0 +1,53 @@
+// How many tools an install puts in front of a model, which is what the tool
+// limit counts. Imports nothing, so node --test runs it directly.
+
+// The same values as constants.TOOL_DEFINITION_KEY_MCP_PROXY and
+// TOOL_DEFINITION_KEY_CUSTOM_CODE, written out rather than imported, since
+// this file imports nothing.
+const MCP_PROXY_TOOL_KEY = 'mcp-proxy';
+const CUSTOM_CODE_TOOL_KEY = 'custom-code';
+
+// The tools an allow-list keeps out of `names`. An empty or absent list keeps
+// all of them, as the MCP boot loop reads it.
+const allowedCount = (names: string[], config: unknown): number => {
+  const allowedTools = (config as { allowedTools?: unknown } | null)
+    ?.allowedTools;
+  if (!Array.isArray(allowedTools) || allowedTools.length === 0) {
+    return names.length;
+  }
+  const allowed = new Set(allowedTools);
+  return names.filter(name => allowed.has(name)).length;
+};
+
+/**
+ * An mcp-proxy row exposes each discovered remote tool its allow-list keeps,
+ * so a single GitHub install can be dozens of tools. A custom-code row exposes
+ * the functions of its published version the allow-list keeps — pass their
+ * names as `customCodeFunctions`; without them the row counts as one. Every
+ * other row is one tool.
+ */
+export const countInstallTools = (
+  install: {
+    toolKey: string;
+    config: unknown;
+    metadata: unknown;
+  },
+  customCodeFunctions?: string[]
+): number => {
+  if (install.toolKey === CUSTOM_CODE_TOOL_KEY) {
+    return customCodeFunctions
+      ? allowedCount(customCodeFunctions, install.config)
+      : 1;
+  }
+  if (install.toolKey !== MCP_PROXY_TOOL_KEY) return 1;
+
+  const discovered = (
+    install.metadata as { discovery?: { tools?: unknown } } | null
+  )?.discovery?.tools;
+  if (!Array.isArray(discovered)) return 0;
+
+  const names = discovered
+    .map(tool => (tool as { name?: unknown } | null)?.name)
+    .filter((name): name is string => typeof name === 'string');
+  return allowedCount(names, install.config);
+};