@zackbart/connecta 0.25.0 → 0.26.1

package/dist/branding.d.ts

@@ -18,6 +18,11 @@ interface ResolvedBranding {
     pageTitle: string;
     /** href for the page's icon link. */
     faviconHref: string;
+    /**
+     * The configured `theme-color`, or the documented `#ffffff` default.
+     * Informational: pages emit a configured value as-is, and without one they
+     * follow the scheme (`themeColorMeta`) rather than painting this default.
+     */
     themeColor: string;
     /** Only the tokens that survived their gate; the stylesheet owns the rest. */
     theme: ResolvedTheme;
@@ -43,6 +48,88 @@ export declare function droppedThemeTokens(theme?: ConnectaTheme): string[];
  * anything that would need escaping is dropped rather than rewritten.
  */
 export declare function themeCss(theme: ResolvedTheme): string;
+/**
+ * The resolved scheme as the root element's attribute. The dark palette keys
+ * off `html[data-scheme]`, so "system" leaves it off and the media query
+ * decides.
+ */
+export declare function schemeAttribute(theme: ResolvedTheme): string;
+/** Text or attribute value, escaped for any position in an HTML document. */
+export declare function escapeHtml(value: string): string;
+export interface PageLayout {
+    /** The complete `<title>`. */
+    title: string;
+    /** Whether the operator UI is mounted, and so serves `/favicon.*` and `/`. */
+    uiMounted: boolean;
+    /**
+     * The origin that serves `/favicon.*`, for a page that may be rendered on
+     * another host: root-relative icon hrefs resolve against it. A browser 404
+     * on the artifact host passes `publicUrl`, since that host answers every
+     * non-artifact path, the favicons included, with 404. Omitted, they stay
+     * root-relative.
+     */
+    iconOrigin?: string | undefined;
+    /** Markup after the masthead: the page's `<main>`. */
+    body: string;
+    /**
+     * The page's stylesheet before the theme block. Defaults to the shared
+     * tokens and primitives; the operator shell passes its own bundle, which
+     * already imports both.
+     */
+    styles?: string;
+    /** Page-specific rules appended to `styles`, still before the theme. */
+    extraStyles?: string;
+    /** Additional head markup, emitted verbatim (the Clerk loader). */
+    head?: string;
+    /** Emitted verbatim at the masthead's end (the operator nav mount). */
+    mastheadEnd?: string;
+    /** A skip link to this element id, for pages with navigation to skip. */
+    skipTo?: {
+        id: string;
+        label: string;
+    };
+    /** Markup after the body content, emitted verbatim (the operator script). */
+    tail?: string;
+}
+/**
+ * The one page layout every server-rendered page shares: the operator shell,
+ * the OAuth callback, and browser-facing 404s. Doctype and meta, the favicon a
+ * deployment actually serves, the resolved scheme, the token stylesheet with
+ * the theme block after it, and the masthead.
+ *
+ * `/favicon.svg` and `/favicon.ico` are operator UI routes. Without the UI they
+ * are 404s, so the default links are left out rather than pointing at nothing
+ * (a browser then asks for `/favicon.ico` on its own and gets the same 404). A
+ * configured `favicon.href` is the operator's own icon and is linked either way.
+ *
+ * Every interpolated branding value is escaped here; `body`, `head`,
+ * `mastheadEnd`, and `tail` are the caller's markup and are not.
+ */
+export declare function renderPage(branding: ConnectaBranding | undefined, layout: PageLayout): string;
+/**
+ * Status marks for one-message pages. Decorative: the label and heading beside
+ * each carry the meaning, so the shape repeats it and color is never alone.
+ */
+export declare const STATUS_ICONS: {
+    readonly ok: "<svg viewBox=\"0 0 20 20\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2.2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M5 10.5l3.2 3.2L15 6.8\"/></svg>";
+    readonly problem: "<svg viewBox=\"0 0 20 20\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2.2\" stroke-linecap=\"round\"><path d=\"M10 5.5v5.5\"/><path d=\"M10 14.6v.1\"/></svg>";
+    readonly declined: "<svg viewBox=\"0 0 20 20\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2.2\" stroke-linecap=\"round\"><path d=\"M6 10h8\"/></svg>";
+    readonly missing: "<svg viewBox=\"0 0 20 20\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\"><circle cx=\"9\" cy=\"9\" r=\"4.5\"/><path d=\"M12.4 12.4L16 16\"/></svg>";
+};
+/**
+ * The 404 a browser gets for a path nothing serves, and everyone else's plain
+ * `Not Found`. The body is built from deployment configuration alone and names
+ * no path, so every unserved path — on the main host or an artifact host —
+ * answers with the same bytes for the same `Accept`: a 404 must not tell one
+ * route from another. The home link appears only when the operator UI is
+ * mounted to land on, and points at the public origin so an artifact host's
+ * 404 does not link to another 404.
+ */
+export declare function notFoundResponse(request: Request, opts: {
+    branding?: ConnectaBranding | undefined;
+    ui?: object | undefined;
+    publicUrl?: string | undefined;
+}): Response;
 /**
  * Names of the branding URLs the operator set that failed their gate and were
  * replaced by a default. Lives beside the gates so the startup warning cannot

package/dist/branding.js

@@ -1,3 +1,4 @@
+import { PAGE_CSS, TOKENS_CSS } from "./page-styles.js";
 /** Connecta's default monochrome "C" mark. */
 export const CONNECTA_FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
   <style>
@@ -37,7 +38,7 @@ export function resolveBranding(branding) {
         faviconHref: faviconHref && isSafeIconHref(faviconHref)
             ? faviconHref
             : DEFAULT_FAVICON_HREF,
-        themeColor: trimmedString(branding?.themeColor) ?? "#ffffff",
+        themeColor: configuredThemeColor(branding) ?? "#ffffff",
         theme: resolveTheme(branding?.theme),
     };
 }
@@ -148,6 +149,174 @@ export function themeCss(theme) {
     ].filter(Boolean);
     return declarations.length ? `:root{${declarations.join(";")}}` : "";
 }
+/**
+ * The resolved scheme as the root element's attribute. The dark palette keys
+ * off `html[data-scheme]`, so "system" leaves it off and the media query
+ * decides.
+ */
+export function schemeAttribute(theme) {
+    return theme.colorScheme === "system"
+        ? ""
+        : ` data-scheme="${theme.colorScheme}"`;
+}
+/** Text or attribute value, escaped for any position in an HTML document. */
+export function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+/**
+ * The masthead's `--surface` in each palette, for the browser chrome a
+ * `theme-color` paints. A configured `themeColor` wins; without one a dark
+ * page should not sit under a white status bar.
+ */
+const SURFACE = { light: "#ffffff", dark: "#151a21" };
+/** The operator's own `themeColor`, read the one way both callers read it. */
+function configuredThemeColor(branding) {
+    return trimmedString(branding?.themeColor);
+}
+function themeColorMeta(branding, theme) {
+    const configured = configuredThemeColor(branding);
+    if (configured)
+        return `<meta name="theme-color" content="${escapeHtml(configured)}">`;
+    if (theme.colorScheme !== "system") {
+        return `<meta name="theme-color" content="${SURFACE[theme.colorScheme]}">`;
+    }
+    return `<meta name="theme-color" content="${SURFACE.light}" media="(prefers-color-scheme: light)">\n` +
+        `<meta name="theme-color" content="${SURFACE.dark}" media="(prefers-color-scheme: dark)">`;
+}
+/**
+ * The one page layout every server-rendered page shares: the operator shell,
+ * the OAuth callback, and browser-facing 404s. Doctype and meta, the favicon a
+ * deployment actually serves, the resolved scheme, the token stylesheet with
+ * the theme block after it, and the masthead.
+ *
+ * `/favicon.svg` and `/favicon.ico` are operator UI routes. Without the UI they
+ * are 404s, so the default links are left out rather than pointing at nothing
+ * (a browser then asks for `/favicon.ico` on its own and gets the same 404). A
+ * configured `favicon.href` is the operator's own icon and is linked either way.
+ *
+ * Every interpolated branding value is escaped here; `body`, `head`,
+ * `mastheadEnd`, and `tail` are the caller's markup and are not.
+ */
+export function renderPage(branding, layout) {
+    const brand = resolveBranding(branding);
+    // Top-left corner. With an owner set it reads "<owner> <product>"; without
+    // one the product label stands alone. Either half links out when the
+    // matching URL is configured.
+    const label = (className, text, href) => href
+        ? `<a class="${className} navlink" href="${escapeHtml(href)}">${escapeHtml(text)}</a>`
+        : `<span class="${className}">${escapeHtml(text)}</span>`;
+    const owner = brand.ownerName
+        ? label("brand", brand.ownerName, brand.ownerUrl)
+        : label("brand", brand.productName, brand.productUrl);
+    const product = brand.ownerName
+        ? label("product", brand.productName, brand.productUrl)
+        : "";
+    const customIcon = brand.faviconHref !== DEFAULT_FAVICON_HREF;
+    // `isSafeIconHref` already limited a relative href to one leading slash, so
+    // resolving it can only land on `iconOrigin` itself.
+    const iconHref = (href) => layout.iconOrigin && href.startsWith("/")
+        ? new URL(href, layout.iconOrigin).toString()
+        : href;
+    const icons = [
+        ...(customIcon || layout.uiMounted
+            ? [`<link rel="icon" href="${escapeHtml(iconHref(brand.faviconHref))}" type="image/svg+xml">`]
+            : []),
+        ...(layout.uiMounted
+            ? [`<link rel="shortcut icon" href="${escapeHtml(iconHref("/favicon.ico"))}">`]
+            : []),
+    ];
+    const skip = layout.skipTo
+        ? `<a class="skip-link" href="#${escapeHtml(layout.skipTo.id)}">${escapeHtml(layout.skipTo.label)}</a>\n`
+        : "";
+    const styles = (layout.styles ?? TOKENS_CSS + PAGE_CSS) + (layout.extraStyles ?? "");
+    return `<!doctype html>
+<html lang="en"${schemeAttribute(brand.theme)}>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+${themeColorMeta(branding, brand.theme)}
+<meta name="description" content="${escapeHtml(brand.description)}">
+${icons.join("\n")}
+<title>${escapeHtml(layout.title)}</title>
+${layout.head ?? ""}
+<style>${styles}${themeCss(brand.theme)}</style>
+</head>
+<body>
+${skip}<header class="masthead shell">
+  <div class="masthead-inner">
+    <div class="mast-nav">
+      ${owner}${product ? `\n      ${product}` : ""}
+    </div>${layout.mastheadEnd ? `\n    ${layout.mastheadEnd}` : ""}
+  </div>
+</header>
+${layout.body}${layout.tail ? `\n${layout.tail}` : ""}
+</body>
+</html>`;
+}
+/**
+ * Status marks for one-message pages. Decorative: the label and heading beside
+ * each carry the meaning, so the shape repeats it and color is never alone.
+ */
+export const STATUS_ICONS = {
+    ok: '<svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 10.5l3.2 3.2L15 6.8"/></svg>',
+    problem: '<svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"><path d="M10 5.5v5.5"/><path d="M10 14.6v.1"/></svg>',
+    declined: '<svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"><path d="M6 10h8"/></svg>',
+    missing: '<svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="9" cy="9" r="4.5"/><path d="M12.4 12.4L16 16"/></svg>',
+};
+/**
+ * A request a person's browser made for a page, as opposed to a client asking
+ * for data: navigations send `text/html` in `Accept`, `fetch()` and MCP
+ * clients do not.
+ */
+function wantsHtml(request) {
+    return /\btext\/html\b/i.test(request.headers.get("Accept") ?? "");
+}
+/**
+ * The 404 a browser gets for a path nothing serves, and everyone else's plain
+ * `Not Found`. The body is built from deployment configuration alone and names
+ * no path, so every unserved path — on the main host or an artifact host —
+ * answers with the same bytes for the same `Accept`: a 404 must not tell one
+ * route from another. The home link appears only when the operator UI is
+ * mounted to land on, and points at the public origin so an artifact host's
+ * 404 does not link to another 404.
+ */
+export function notFoundResponse(request, opts) {
+    if (!wantsHtml(request)) {
+        return new Response("Not Found", { status: 404, headers: { Vary: "Accept" } });
+    }
+    const brand = resolveBranding(opts.branding);
+    const uiMounted = Boolean(opts.ui);
+    const homeHref = opts.publicUrl ? new URL("/", opts.publicUrl).toString() : "/";
+    const home = uiMounted
+        ? `<div class="status-actions"><a class="btn" href="${escapeHtml(homeHref)}">Go to ${escapeHtml(brand.productName)}</a></div>`
+        : "";
+    const body = `<main class="page shell">
+  <section class="status-page" data-not-found>
+    <div class="status-head">
+      <span class="status-mark" aria-hidden="true">${STATUS_ICONS.missing}</span>
+      <p class="status-label">404</p>
+    </div>
+    <h1>Page not found</h1>
+    <p class="status-copy">Nothing is served at this address. Check the link, or ask whoever runs ${escapeHtml(brand.productName)} for the right one.</p>
+    ${home}
+  </section>
+</main>`;
+    return new Response(renderPage(opts.branding, {
+        title: `Page not found — ${brand.pageTitle}`,
+        uiMounted,
+        // Same bytes on either host: the icons, like the home link, come from
+        // the public origin.
+        iconOrigin: opts.publicUrl,
+        body,
+    }), {
+        status: 404,
+        headers: { "Content-Type": "text/html; charset=utf-8", Vary: "Accept" },
+    });
+}
 /**
  * Whether the operator meant to supply a value here — the question every
  * dropped-value warning asks before naming a field, and one definition so the

package/dist/catalog-service.js

@@ -1,11 +1,12 @@
-import { Deferred, Effect, Exit, Result } from "effect";
+import { Effect, Result } from "effect";
 import { compactDiscoverySchema, compactDescriptionSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, matchesLexicalTerm, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, typescriptSignature, } from "./catalog.js";
 import { resolveDiscoveryConcurrency } from "./concurrency.js";
 import { boundedEchoText, classifyCallError, framingError, } from "./errors.js";
 import { connectorGuide, connectorGuideRequired, connectorGuideSummary, connectorSkillName, } from "./skills.js";
 import { runEdge, withDeadlineEffect } from "./runtime/run.js";
+import { SharedRead } from "./runtime/shared-read.js";
 import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, } from "./timeout.js";
-import { isExplicitlyReadOnly } from "./tool-safety.js";
+import { isApprovalExempt, isExplicitlyReadOnly, NO_EXEMPTIONS, } from "./tool-safety.js";
 export const DEFAULT_SEARCH_LIMIT = 8;
 export const MAX_SEARCH_LIMIT = 100;
 export const MAX_DESCRIBE_ADDRESSES = 100;
@@ -202,12 +203,13 @@ export class CatalogService {
     searchRoute;
     readOptions;
     requestSignal;
-    // The request-scoped catalog cache: one Deferred per connector asked about,
-    // completed by the first asker's registry read and joined by every later
-    // one. A success stays for the rest of the request, so a search and the call
-    // after it see one catalog; a failure is dropped so the next ask reads
-    // again. The service lives and dies with one request, so no Deferred here is
-    // ever awaited from another.
+    approval;
+    // The request-scoped catalog cache: one shared read per connector asked
+    // about, started by the first asker and joined by every later one. A
+    // success stays for the rest of the request, so a search and the call after
+    // it see one catalog; a failure, or a read cancelled because every asker
+    // left it, is dropped so the next ask reads again. The service lives and
+    // dies with one request, so no read here is ever awaited from another.
     //
     // Registry.getTools also joins concurrent reads in one request scope, which
     // the operator UI and status reads rely on. This map overlaps it only for
@@ -218,6 +220,7 @@ export class CatalogService {
     constructor(registry, baseUrl, options = {}) {
         this.registry = registry;
         this.baseUrl = baseUrl;
+        this.approval = options.approval ?? NO_EXEMPTIONS;
         this.requestScope = options.requestScope ?? {};
         this.probeTimeoutMs =
             normalizeTimeoutMs(options.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
@@ -256,28 +259,27 @@ export class CatalogService {
         return runEdge(this.catalog(id, callOptions));
     }
     // One connector's catalog from the request-scoped cache, reading it through
-    // the registry when this request has not yet. The first asker's options
-    // govern the read and a joiner shares its outcome, as the registry's own
-    // flight below does. The read settles the Deferred itself, not the asker's
-    // fiber, so a probe deadline ends one asker's wait and never the read.
+    // the registry when this request has not yet. No asker's options govern the
+    // read: it carries its own signal and the catalog deadline, the probe
+    // timeout, whichever asker starts it. Each asker waits under its own signal
+    // and deadline, so a short-deadline call that starts the read and a search
+    // that joins it each end on their own terms, and the read is cancelled only
+    // once every asker has gone (#571).
     catalog(id, callOptions) {
         return Effect.suspend(() => {
-            const cached = this.catalogs.get(id);
-            if (cached)
-                return Deferred.await(cached);
-            const read = Deferred.makeUnsafe();
-            this.catalogs.set(id, read);
-            // The executor turns a synchronous throw from getTools into a rejection.
-            new Promise((resolve) => resolve(this.registry.getTools(id, this.baseUrl, this.requestScope, callOptions, this.readOptions))).then((tools) => {
-                Deferred.doneUnsafe(read, Exit.succeed(tools));
-            }, (cause) => {
-                // Evicted before the Deferred resumes anyone, so an asker that
-                // retries on hearing of the failure starts a fresh read.
-                if (this.catalogs.get(id) === read)
-                    this.catalogs.delete(id);
-                Deferred.doneUnsafe(read, Exit.fail(cause));
-            });
-            return Deferred.await(read);
+            let read = this.catalogs.get(id);
+            if (!read) {
+                const started = new SharedRead((signal) => this.registry.getTools(id, this.baseUrl, this.requestScope, { signal, timeoutMs: this.probeTimeoutMs }, this.readOptions), (succeeded) => {
+                    // Evicted before the read resumes anyone, so an asker that
+                    // retries on hearing of the failure starts a fresh read.
+                    if (!succeeded && this.catalogs.get(id) === started) {
+                        this.catalogs.delete(id);
+                    }
+                });
+                this.catalogs.set(id, started);
+                read = started;
+            }
+            return read.join(callOptions.signal);
         });
     }
     // Every named catalog under its own probe deadline, `concurrency` at a time,
@@ -286,7 +288,7 @@ export class CatalogService {
     // A probe also ends with its request, so no listing outlives the caller
     // that asked for it.
     discoveryCatalogs(ids, route) {
-        return Effect.forEach(ids, (id) => Effect.result(withDeadlineEffect((signal) => this.catalog(id, { signal, timeoutMs: this.probeTimeoutMs }), {
+        return Effect.forEach(ids, (id) => Effect.result(withDeadlineEffect((signal) => this.catalog(id, { signal }), {
             ...(this.requestSignal ? { signal: this.requestSignal } : {}),
             timeoutMs: this.probeTimeoutMs,
             timeoutError: new Error(`${route} probe of "${id}" timed out after ${this.probeTimeoutMs}ms`),
@@ -536,6 +538,11 @@ export class CatalogService {
                     ...(match.tool.annotations
                         ? { annotations: match.tool.annotations }
                         : {}),
+                    // Config lets a program call this write without pausing (#566).
+                    // A marker, not a class: the tool stays approval-required.
+                    ...(isApprovalExempt(this.approval, match.connector, match.tool.name, match.tool)
+                        ? { approval: "exempt" }
+                        : {}),
                     ...(requiredReasons
                         ? {
                             guideRequired: true,
@@ -847,6 +854,9 @@ export class CatalogService {
                     : {}),
                 ...(output.source ? { outputSchemaSource: output.source } : {}),
                 ...(tool.annotations ? { annotations: tool.annotations } : {}),
+                ...(isApprovalExempt(this.approval, addressResolution.connector, tool.name, tool)
+                    ? { approval: "exempt" }
+                    : {}),
             };
         });
     }

package/dist/catalog.js

@@ -14,6 +14,12 @@ class SchemaWork {
     remaining = MAX_SCHEMA_WORK;
     truncated = false;
     refs = new Map();
+    /**
+     * Renderings whose top level is a bare `|` or `&`, recorded as the walk
+     * produces them. Compact carries raw keys and `//` prose, so unlike the
+     * TypeScript dialect its text cannot be rescanned for a top-level operator.
+     */
+    ungrouped = new Set();
     constructor(byteLimit = MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
         this.byteLimit = byteLimit;
     }
@@ -435,8 +441,11 @@ function renderEnum(values, work, byteLimit, onTruncated) {
         const full = prefix.join(" | ");
         if (schemaEncoder.encode(full).length > limit)
             break;
-        if (index === values.length - 1)
+        if (index === values.length - 1) {
+            if (index > 0)
+                work.ungrouped.add(full);
             return full;
+        }
         const omitted = values.length - prefix.length;
         const candidate = `(${full} | ${marker(omitted)})`;
         if (schemaEncoder.encode(candidate).length <= limit)
@@ -582,6 +591,12 @@ function renderSchema(schema, defs, seen, depth, options) {
 function renderSchemaNode(schema, defs, seen, depth, options) {
     const ts = options.typescript === true;
     const group = ts ? groupedType : grouped;
+    const ungrouped = options.work.ungrouped;
+    // A `[]` suffix binds tighter than `|` and `&`, so an element rendered at
+    // operator level needs parentheses or it reads as its last member's array.
+    const element = (rendered) => ts
+        ? groupedType(rendered)
+        : ungrouped.has(rendered) ? `(${rendered})` : rendered;
     if (depth > 4) {
         if (!ts)
             return "…";
@@ -607,9 +622,17 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
             : "unknown";
         return rendered === "unknown" ? rendered : `${rendered} | null`;
     }
-    const constrain = (rendered) => options.renderConstraints
-        ? renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated)
-        : rendered;
+    const constrain = (rendered) => {
+        if (!options.renderConstraints)
+            return rendered;
+        const result = renderConstraints(rendered, s, options.constraintByteLimit, options.onConstraintTruncated);
+        // Constraints parenthesize a union before their comment but leave an
+        // intersection bare, and a comment does not group what precedes it.
+        if (ungrouped.has(rendered) && !result.startsWith(`(${rendered})`)) {
+            ungrouped.add(result);
+        }
+        return result;
+    };
     // Conditions cannot be expressed by a single static shape. Preserve the
     // base and send callers to the exact schema instead of hiding the rules.
     if (s.dependentSchemas !== undefined || s.if !== undefined ||
@@ -623,7 +646,10 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
         const rendered = declaresShape(base)
             ? renderSchema(base, defs, seen, depth, options)
             : "unknown";
-        return `${rendered} /* conditional */`;
+        const result = `${rendered} /* conditional */`;
+        if (ungrouped.has(rendered))
+            ungrouped.add(result);
+        return result;
     }
     // allOf composes rather than replaces: it is checked before every other
     // shape keyword, and renders the schema's own shape alongside its members instead
@@ -653,7 +679,10 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
         }
         if (parts.length === 0)
             return "unknown";
-        return parts.finish();
+        const rendered = parts.finish();
+        if (parts.length > 1)
+            ungrouped.add(rendered);
+        return rendered;
     }
     const reference = s.$ref ?? s.$dynamicRef;
     if (typeof reference === "string") {
@@ -693,6 +722,8 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
             parts.add(renderSchema(member, defs, seen, depth + 1, options));
         }
         const rendered = parts.finish() || "unknown";
+        if (parts.length > 1)
+            ungrouped.add(rendered);
         return constrain(rendered);
     }
     if (Array.isArray(s.enum)) {
@@ -743,7 +774,7 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
             const rest = s.items === undefined || s.items === true
                 ? "unknown"
                 : renderSchema(s.items, defs, seen, depth + 1, options);
-            parts.add(`...${group(rest)}[]`);
+            parts.add(`...${element(rest)}[]`);
         }
         return parts.finish();
     }
@@ -751,7 +782,7 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
         const items = s.items
             ? renderSchema(s.items, defs, seen, depth + 1, options)
             : "unknown";
-        return ts ? `${groupedType(items)}[]` : `${items}[]`;
+        return `${element(items)}[]`;
     }
     if (type === "object" || s.properties) {
         const props = (s.properties ?? {});
@@ -809,6 +840,8 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
             parts.add(options.work.text(String(item)));
         }
         const rendered = parts.finish();
+        if (parts.length > 1)
+            ungrouped.add(rendered);
         return constrain(rendered);
     }
     if (options.renderConstraints && constraintEntries(s).length > 0) {
@@ -959,6 +992,7 @@ function boundedCompactSchema(schema, description, typescript = false) {
         // are memoized only within each pass because their text includes constraints.
         if (error === schemaSizeExceeded && !description) {
             work.refs.clear();
+            work.ungrouped.clear();
             try {
                 return {
                     text: renderSchema(schema, schema, new Set(), 0, {

package/dist/connector-access.d.ts

@@ -9,20 +9,33 @@ export declare const POOL_NAME_RE: RegExp;
 /**
  * One derived view: which connectors, and for connectors granted by address
  * only, which tools. A connector absent from `toolAccess` is visible whole.
+ * `guardedToolAccess` is a subset of `toolAccess` checked against the loaded
+ * catalog each time tools are discovered or invoked.
  */
 export interface ConnectorAccess {
     connectorIds: "all" | readonly string[];
     toolAccess?: ToolAccess;
+    /** Exact tool grants that also require a current explicit read-only annotation. */
+    guardedToolAccess?: ToolAccess;
 }
+interface ReadOnlyToolGrant {
+    tool: string;
+    requireReadOnly: true;
+}
+export type ConnectorGrant = string | ReadOnlyToolGrant;
 /**
  * Normalize a grant list. A bare connector id grants every tool on that
  * connector; a `connector.tool` address grants one tool. Grants are additive,
  * so a bare id beside addresses for the same connector means the whole
- * connector. Anything else — an unknown shape, an empty tool name, a
- * non-string — throws, and the caller decides whether that is a construction
- * failure or a 403: a grant that cannot be parsed must never fail open.
+ * connector. Identity resolution can opt into `{ tool, requireReadOnly: true }`
+ * for a fixed address that also needs a current explicit read-only annotation;
+ * pool declarations remain strings. Anything else throws, and the caller
+ * decides whether that is a construction failure or a 403: a grant that
+ * cannot be parsed must never fail open.
  */
-export declare function parseConnectorAccess(value: unknown): ConnectorAccess;
+export declare function parseConnectorAccess(value: unknown, options?: {
+    allowReadOnly?: boolean;
+}): ConnectorAccess;
 /**
  * The view a pool endpoint serves: the pool's grants, never wider than the
  * identity's own. A connector or tool outside either side is gone; a
@@ -30,3 +43,4 @@ export declare function parseConnectorAccess(value: unknown): ConnectorAccess;
  * only narrow what the identity resolver already allowed.
  */
 export declare function intersectAccess(ceiling: ConnectorAccess, pool: ConnectorAccess): ConnectorAccess;
+export {};