@zackbart/connecta 0.24.2 → 0.24.4

package/dist/branding.d.ts

@@ -1,6 +1,13 @@
-import type { ConnectaBranding, UiAuthConfig } from "./types.js";
+import type { ConnectaBranding, ConnectaTheme, UiAuthConfig } from "./types.js";
 /** Connecta's default monochrome "C" mark. */
 export declare const CONNECTA_FAVICON_SVG = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 32 32\">\n  <style>\n    .fg { fill: #000 }\n    @media (prefers-color-scheme: dark) { .fg { fill: #fff } }\n  </style>\n  <path class=\"fg\" d=\"M27 9.4A13 13 0 1 0 27 22.6l-4.4-2.5a8 8 0 1 1 0-8.2z\"/>\n</svg>";
+export interface ResolvedTheme {
+    accent?: string;
+    radius?: string;
+    fontFamily?: string;
+    monoFamily?: string;
+    colorScheme: "system" | "light" | "dark";
+}
 interface ResolvedBranding {
     productName: string;
     productUrl?: string;
@@ -12,8 +19,30 @@ interface ResolvedBranding {
     /** href for the page's icon link. */
     faviconHref: string;
     themeColor: string;
+    /** Only the tokens that survived their gate; the stylesheet owns the rest. */
+    theme: ResolvedTheme;
 }
 export declare function resolveBranding(branding?: ConnectaBranding): ResolvedBranding;
+/**
+ * Read a theme the way branding URLs are read: gate every field, drop what
+ * fails, never throw. This runs during `createConnecta`, so a malformed value
+ * has to fall back to the stylesheet default instead of refusing to serve the
+ * page. `droppedThemeTokens` names the drops for the startup warning.
+ */
+export declare function resolveTheme(theme?: ConnectaTheme): ResolvedTheme;
+/**
+ * Names of the theme tokens the operator set that failed their gate. Same
+ * contract as `droppedBrandingUrls`: rendering falls back silently, so this is
+ * the only place an operator learns their value never reached the page.
+ */
+export declare function droppedThemeTokens(theme?: ConnectaTheme): string[];
+/**
+ * The resolved theme as a `:root` block, or "" when a deployment configured
+ * nothing. It is emitted after the stylesheet so it overrides the defaults.
+ * There is no escaping here: every value has already passed a gate above, and
+ * anything that would need escaping is dropped rather than rewritten.
+ */
+export declare function themeCss(theme: ResolvedTheme): string;
 /**
  * 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
@@ -55,7 +84,7 @@ export declare function isSafeHttpsUrl(url: unknown): boolean;
  * `frontendApiUrl` is required, so anything that fails its gate is a drop.
  * `signInUrl` and `signUpUrl` are optional, so only a value the operator
  * *supplied* and the gate then rejected is worth a warning — an unset field
- * took no default away from anyone. `isSetUrlValue` decides that, the same way
+ * took no default away from anyone. `isSetValue` decides that, the same way
  * and for the same reasons it decides it for the branding URLs: a warning that
  * fires for one and not the other would be reporting on the field rather than
  * on the operator's intent. Rendering is not consulted for this: it drops on

package/dist/branding.js

@@ -38,17 +38,125 @@ export function resolveBranding(branding) {
             ? faviconHref
             : DEFAULT_FAVICON_HREF,
         themeColor: trimmedString(branding?.themeColor) ?? "#ffffff",
+        theme: resolveTheme(branding?.theme),
     };
 }
+/**
+ * Hex colors only: `#rgb`, `#rrggbb`, `#rrggbbaa`. A hex value cannot carry a
+ * `url()`, a `var()`, or a closing brace into the `:root` block it is written
+ * into, which is the whole reason the gate is this narrow.
+ */
+const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+/** A single non-negative CSS length, or a bare number the caller reads as px. */
+const CSS_LENGTH = /^(?:0|[0-9]{1,3}(?:\.[0-9]{1,3})?)(px|rem|em)?$/;
+/**
+ * One family name: bare, or wrapped in matching quotes. The character class
+ * excludes everything CSS needs to end a declaration or open a function (`;`,
+ * `{`, `}`, `(`, `)`, backslash, `<`, `>`, `@`, `*`, `/`, `:`), and matched
+ * quotes mean the value cannot leave an open string that swallows the CSS
+ * after it.
+ */
+const FONT_NAME = /^(?:"[a-z0-9 ._-]+"|'[a-z0-9 ._-]+'|[a-z][a-z0-9 ._-]*)$/i;
+/** A font-family list: comma-separated names and nothing else. */
+function isFontStack(value) {
+    if (value.length > 200)
+        return false;
+    const names = value.split(",");
+    return names.length <= 12 &&
+        names.every((name) => FONT_NAME.test(name.trim()));
+}
+const COLOR_SCHEMES = ["system", "light", "dark"];
+/**
+ * Read a theme the way branding URLs are read: gate every field, drop what
+ * fails, never throw. This runs during `createConnecta`, so a malformed value
+ * has to fall back to the stylesheet default instead of refusing to serve the
+ * page. `droppedThemeTokens` names the drops for the startup warning.
+ */
+export function resolveTheme(theme) {
+    const accent = trimmedString(theme?.accent);
+    const fontFamily = trimmedString(theme?.fontFamily);
+    const monoFamily = trimmedString(theme?.monoFamily);
+    const scheme = trimmedString(theme?.colorScheme);
+    const radius = radiusLength(theme?.radius);
+    return {
+        ...(accent && HEX_COLOR.test(accent) ? { accent } : {}),
+        ...(radius !== undefined ? { radius } : {}),
+        ...(fontFamily && isFontStack(fontFamily) ? { fontFamily } : {}),
+        ...(monoFamily && isFontStack(monoFamily) ? { monoFamily } : {}),
+        colorScheme: COLOR_SCHEMES.includes(scheme)
+            ? scheme
+            : "system",
+    };
+}
+/**
+ * `radius` accepts a number as well as a string, since a config file is more
+ * likely to say `10` than `"10px"`. A bare number means pixels; a string must
+ * carry its own unit or be zero.
+ */
+function radiusLength(radius) {
+    if (typeof radius === "number") {
+        return Number.isFinite(radius) && radius >= 0 && radius <= 999
+            ? `${radius}px`
+            : undefined;
+    }
+    const value = trimmedString(radius);
+    if (!value || !CSS_LENGTH.test(value))
+        return undefined;
+    return /[a-z]$/i.test(value) || value === "0" ? value : `${value}px`;
+}
+/**
+ * Names of the theme tokens the operator set that failed their gate. Same
+ * contract as `droppedBrandingUrls`: rendering falls back silently, so this is
+ * the only place an operator learns their value never reached the page.
+ */
+export function droppedThemeTokens(theme) {
+    if (!theme)
+        return [];
+    const resolved = resolveTheme(theme);
+    const dropped = [];
+    if (isSetValue(theme.accent) && !resolved.accent)
+        dropped.push("accent");
+    if (isSetValue(theme.radius) && resolved.radius === undefined) {
+        dropped.push("radius");
+    }
+    if (isSetValue(theme.fontFamily) && !resolved.fontFamily) {
+        dropped.push("fontFamily");
+    }
+    if (isSetValue(theme.monoFamily) && !resolved.monoFamily) {
+        dropped.push("monoFamily");
+    }
+    // Compared against the trimmed value the resolver reads, so `" dark "` is
+    // not reported as dropped when it was applied.
+    if (isSetValue(theme.colorScheme) &&
+        trimmedString(theme.colorScheme) !== resolved.colorScheme) {
+        dropped.push("colorScheme");
+    }
+    return dropped.map((token) => `theme.${token}`);
+}
+/**
+ * The resolved theme as a `:root` block, or "" when a deployment configured
+ * nothing. It is emitted after the stylesheet so it overrides the defaults.
+ * There is no escaping here: every value has already passed a gate above, and
+ * anything that would need escaping is dropped rather than rewritten.
+ */
+export function themeCss(theme) {
+    const declarations = [
+        theme.accent ? `--accent:${theme.accent}` : "",
+        theme.radius !== undefined ? `--radius:${theme.radius}` : "",
+        theme.fontFamily ? `--sans:${theme.fontFamily}` : "",
+        theme.monoFamily ? `--mono:${theme.monoFamily}` : "",
+    ].filter(Boolean);
+    return declarations.length ? `:root{${declarations.join(";")}}` : "";
+}
 /**
  * Whether the operator meant to supply a value here — the question every
- * dropped-URL warning asks before naming a field, and one definition so the
+ * dropped-value warning asks before naming a field, and one definition so the
  * branding and `uiAuth` warnings cannot answer it differently. A non-string
  * counts as set: the intent was there and is exactly what the warning reports
  * on. A blank or whitespace-only string does not; that is indistinguishable
  * from leaving the field alone, and both take the default silently.
  */
-function isSetUrlValue(value) {
+function isSetValue(value) {
     return typeof value === "string"
         ? trimmedString(value) !== undefined
         : value !== undefined && value !== null;
@@ -65,13 +173,13 @@ export function droppedBrandingUrls(branding) {
     const resolved = resolveBranding(branding);
     const faviconHref = branding.favicon?.href;
     return [
-        ...(isSetUrlValue(branding.productUrl) && !resolved.productUrl
+        ...(isSetValue(branding.productUrl) && !resolved.productUrl
             ? ["productUrl"]
             : []),
-        ...(isSetUrlValue(branding.ownerUrl) && !resolved.ownerUrl
+        ...(isSetValue(branding.ownerUrl) && !resolved.ownerUrl
             ? ["ownerUrl"]
             : []),
-        ...(isSetUrlValue(faviconHref) &&
+        ...(isSetValue(faviconHref) &&
             trimmedString(faviconHref) !== resolved.faviconHref
             ? ["favicon.href"]
             : []),
@@ -153,7 +261,7 @@ export function isSafeHttpsUrl(url) {
  * `frontendApiUrl` is required, so anything that fails its gate is a drop.
  * `signInUrl` and `signUpUrl` are optional, so only a value the operator
  * *supplied* and the gate then rejected is worth a warning — an unset field
- * took no default away from anyone. `isSetUrlValue` decides that, the same way
+ * took no default away from anyone. `isSetValue` decides that, the same way
  * and for the same reasons it decides it for the branding URLs: a warning that
  * fires for one and not the other would be reporting on the field rather than
  * on the operator's intent. Rendering is not consulted for this: it drops on
@@ -166,10 +274,10 @@ export function droppedUiAuthUrls(uiAuth) {
         return [];
     return [
         ...(isSafeHttpsUrl(uiAuth.frontendApiUrl) ? [] : ["uiAuth.frontendApiUrl"]),
-        ...(isSetUrlValue(uiAuth.signInUrl) && !isSafeHttpsUrl(uiAuth.signInUrl)
+        ...(isSetValue(uiAuth.signInUrl) && !isSafeHttpsUrl(uiAuth.signInUrl)
             ? ["uiAuth.signInUrl"]
             : []),
-        ...(isSetUrlValue(uiAuth.signUpUrl) && !isSafeHttpsUrl(uiAuth.signUpUrl)
+        ...(isSetValue(uiAuth.signUpUrl) && !isSafeHttpsUrl(uiAuth.signUpUrl)
             ? ["uiAuth.signUpUrl"]
             : []),
     ];

package/dist/call-admission.d.ts

@@ -36,6 +36,8 @@ export interface ConnectorCallAdmissionSnapshot {
         max: number;
     };
 }
+/** Sum gauges and counters without publishing connector or principal keys. */
+export declare function aggregateCallAdmissionSnapshots(snapshots: readonly ConnectorCallAdmissionSnapshot[]): ConnectorCallAdmissionSnapshot;
 /**
  * Per-runtime, per-connector call admission. State contains only bounded
  * partition keys, counters, timestamps, signals, and promise continuations;
@@ -64,6 +66,8 @@ export declare class ConnectorCallAdmissionController {
     acquire(input: Readonly<ConnectorCallAdmissionInput> & {
         signal?: AbortSignal;
     }): Promise<CallAdmissionPermit>;
+    /** A principal registry may be evicted only after calls and budgets drain. */
+    isIdle(): boolean;
     snapshot(): ConnectorCallAdmissionSnapshot;
     close(): void;
     private admit;

package/dist/call-admission.js

@@ -22,6 +22,27 @@ export class CallAdmissionError extends ConnectorCallError {
 export function isCallAdmissionError(error) {
     return error instanceof CallAdmissionError;
 }
+/** Sum gauges and counters without publishing connector or principal keys. */
+export function aggregateCallAdmissionSnapshots(snapshots) {
+    const aggregate = {
+        rules: 0, partitions: 0, active: 0, queued: 0, closed: snapshots.length > 0,
+        totals: { admitted: 0, queued: 0, rejected: 0, rateLimited: 0, cancelled: 0 },
+        queueWaitMs: { count: 0, total: 0, max: 0 },
+    };
+    for (const snapshot of snapshots) {
+        for (const key of ["rules", "partitions", "active", "queued"]) {
+            aggregate[key] += snapshot[key];
+        }
+        aggregate.closed &&= snapshot.closed;
+        for (const key of ["admitted", "queued", "rejected", "rateLimited", "cancelled"]) {
+            aggregate.totals[key] += snapshot.totals[key];
+        }
+        aggregate.queueWaitMs.count += snapshot.queueWaitMs.count;
+        aggregate.queueWaitMs.total += snapshot.queueWaitMs.total;
+        aggregate.queueWaitMs.max = Math.max(aggregate.queueWaitMs.max, snapshot.queueWaitMs.max);
+    }
+    return aggregate;
+}
 function positiveWhole(value, name) {
     if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) {
         throw new TypeError(`${name} must be a positive whole number.`);
@@ -194,6 +215,11 @@ export class ConnectorCallAdmissionController {
                 waiter.onAbort();
         });
     }
+    /** A principal registry may be evicted only after calls and budgets drain. */
+    isIdle() {
+        this.evictIdlePartitions(Date.now());
+        return this.partitions.size === 0;
+    }
     snapshot() {
         let active = 0;
         let queued = 0;

package/dist/catalog-drift.js

@@ -36,15 +36,20 @@ export function boundedCatalogDrift(report) {
 }
 const encoder = new TextEncoder();
 /** Deterministic JSON: object keys sorted, so key order is not a schema change. */
-function canonicalize(value) {
-    if (Array.isArray(value))
-        return value.map(canonicalize);
+function canonicalize(value, depth = 0) {
+    // Drift is advisory. Beyond this bound compare an explicit marker instead
+    // of letting a downstream schema exhaust the host stack.
+    if (depth > 64)
+        return "[schema depth truncated]";
+    if (Array.isArray(value)) {
+        return value.map((item) => canonicalize(item, depth + 1));
+    }
     if (value === null || typeof value !== "object")
         return value;
     const entries = Object.entries(value)
         .filter(([, item]) => item !== undefined)
         .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-    return Object.fromEntries(entries.map(([key, item]) => [key, canonicalize(item)]));
+    return Object.fromEntries(entries.map(([key, item]) => [key, canonicalize(item, depth + 1)]));
 }
 /**
  * Digest the schemas of one downstream tool.

package/dist/catalog-service.d.ts

@@ -114,6 +114,8 @@ export interface CatalogDescription {
     inputSchema?: unknown;
     outputSchema?: unknown;
     outputSchemaSource?: "observed";
+    inputSchemaTruncated?: true;
+    outputSchemaTruncated?: true;
     annotations?: ToolDef["annotations"];
     error?: string;
     errorDetails?: CatalogDescriptionFailureDetail;

package/dist/catalog-service.js

@@ -1,4 +1,4 @@
-import { compactDiscoverySchema, compactSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, matchesLexicalTerm, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, } from "./catalog.js";
+import { compactDiscoverySchema, compactDescriptionSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, matchesLexicalTerm, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, } from "./catalog.js";
 import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concurrency.js";
 import { boundedEchoText, classifyCallError, framingError, } from "./errors.js";
 import { connectorGuide, connectorGuideRequired, connectorGuideSummary, connectorSkillName, } from "./skills.js";
@@ -180,9 +180,6 @@ function schemaKeyMetadata(input, output) {
             : {}),
     };
 }
-function renderSchema(schema, format) {
-    return format === "json" ? schema : compactSchema(schema);
-}
 function renderSearchSchema(schema, format) {
     if (format === "json")
         return { schema, truncated: false };
@@ -337,11 +334,25 @@ export class CatalogService {
         };
     }
     async search(args) {
+        if (args.query !== undefined && typeof args.query !== "string") {
+            throw new DiscoveryPolicyError("invalid_args", "query must be a string. Omit it or use an empty string to browse the catalog.");
+        }
+        if (args.connector !== undefined &&
+            boundedEchoText(args.connector) !== args.connector) {
+            // The scope is echoed back as `queryAnalysis.connectorScope`; a clipped
+            // copy could name a different connector, so refuse instead of clamping.
+            throw new DiscoveryPolicyError("invalid_args", "connector must be at most 512 UTF-8 bytes.");
+        }
         const query = args.query ?? "";
         const retrievalQuery = lexicalSearchQuery(query);
         const safety = discoverySafety(args.safety);
         const limit = discoverySearchLimit(args.limit);
-        const offset = Math.max(0, Math.trunc(args.offset ?? 0));
+        if (args.offset !== undefined && (typeof args.offset !== "number" ||
+            !Number.isInteger(args.offset) ||
+            args.offset < 0)) {
+            throw new DiscoveryPolicyError("invalid_args", "offset must be a non-negative whole number. Start at 0 or use the previous page's nextOffset.");
+        }
+        const offset = args.offset ?? 0;
         const scopedConnector = args.connector
             ? this.registry.getConnector(args.connector)
             : undefined;
@@ -768,7 +779,11 @@ export class CatalogService {
             const input = tool.inputSchema ?? { type: "object" };
             const output = this.outputSchema(addressResolution.connector.id, tool);
             const description = summarizeDescription(tool.description, args.fullDescriptions === true);
-            const requiredReasons = guideRequiredReasons(addressResolution.connector, tool, false);
+            const compactInput = format === "compact"
+                ? compactDescriptionSchema(input) : undefined;
+            const compactOutput = format === "compact" && output.schema
+                ? compactDescriptionSchema(output.schema) : undefined;
+            const requiredReasons = guideRequiredReasons(addressResolution.connector, tool, compactInput?.truncated === true || compactOutput?.truncated === true);
             const guideSummary = connectorGuideSummary(addressResolution.connector);
             return {
                 address,
@@ -786,10 +801,12 @@ export class CatalogService {
                         guideRequiredReasons: requiredReasons,
                     }
                     : {}),
-                inputSchema: renderSchema(input, format),
+                inputSchema: compactInput?.text ?? input,
+                ...(compactInput?.truncated ? { inputSchemaTruncated: true } : {}),
+                ...(compactOutput?.truncated ? { outputSchemaTruncated: true } : {}),
                 ...(output.schema
                     ? {
-                        outputSchema: renderSchema(output.schema, format),
+                        outputSchema: compactOutput?.text ?? output.schema,
                     }
                     : {}),
                 ...(output.source ? { outputSchemaSource: output.source } : {}),

package/dist/catalog.d.ts

@@ -50,6 +50,8 @@ export declare function lexicalCorpusStatistics(toolSets: ToolDef[][], query: st
 export declare function rankTools(tools: ToolDef[], query: string, mode?: LexicalMatchMode, statistics?: LexicalCorpusStatistics, exactNameQuery?: string): RankedTool[];
 /** Render and cache a compact TypeScript-like representation of JSON Schema. */
 export declare function compactSchema(schema: JsonSchema): string;
+/** Describe allows 8 KiB for property prose, with the same work cap as search. */
+export declare function compactDescriptionSchema(schema: JsonSchema): CompactDiscoverySchema;
 export interface CompactDiscoverySchema {
     text: string;
     truncated: boolean;