@zackbart/connecta 0.28.1 → 0.30.0

package/dist/ui.js

@@ -1,59 +1,50 @@
+import { assertKnownOptions, keys, optionsOf } from "./config-schema.js";
 import { routeUi } from "./routes/ui.js";
 import { routeCredentials } from "./routes/credentials.js";
 import { routeOAuthManagement } from "./routes/oauth-management.js";
 import { uiData } from "./routes/ui-data.js";
 import { runEdge } from "./runtime/run.js";
-import { isExplicitlyReadOnly } from "./tool-safety.js";
-import { OPERATOR_UI_CSS, OPERATOR_UI_SCRIPT, } from "./operator-ui/generated.js";
+import { OPERATOR_UI_STYLE_PATH, OPERATOR_UI_SCRIPT_PATH, OPERATOR_UI_NOTICES_PATH } from "./operator-ui/generated.js";
 export { filterUiConnectors, } from "./operator-ui/model.js";
-import { escapeHtml, isSafeHttpsUrl, notFoundResponse, renderPage, resolveBranding, } from "./branding.js";
+import { escapeHtml, isSafeHttpsUrl, renderPage, resolveBranding } from "./branding.js";
 export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, isSafeIconHref } from "./branding.js";
-/**
- * A JS string literal safe to inline in a script element. Escaping `/` keeps
- * an operator-supplied `</script>` from terminating the element early.
- */
-function stringForInlineScript(value) {
-    return JSON.stringify(value).replace(/\//g, "\\/");
-}
 const OPERATOR_PAGE_LABELS = {
-    connections: "Connections",
+    overview: "Overview",
+    connections: "Connectors",
+    connector: "Connector",
+    tools: "Tools",
+    access: "Access",
+    config: "Config",
     tokens: "Access tokens",
     activity: "Activity",
-    artifacts: "Artifacts",
-    artifact: "Artifact",
 };
-/** `/artifacts/<id>` and its snapshots, `/artifacts/<id>/v/<version>`. */
-const ARTIFACT_PAGE = /^\/artifacts\/[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?(?:\/v\/\d{1,9})?$/;
 export function operatorPageForPath(path) {
-    if (path === "/tokens")
-        return "tokens";
     if (path === "/")
+        return "overview";
+    if (path === "/connectors")
         return "connections";
+    if (/^\/connectors\/[a-z0-9_-]+$/.test(path))
+        return "connector";
+    if (path === "/tools")
+        return "tools";
+    if (path === "/access")
+        return "access";
+    if (path === "/config")
+        return "config";
+    if (path === "/tokens")
+        return "tokens";
     if (path === "/activity")
         return "activity";
-    if (path === "/artifacts")
-        return "artifacts";
-    if (ARTIFACT_PAGE.test(path))
-        return "artifact";
     return undefined;
 }
-/** Everything artifact pages own: shells, their API, and the frame. */
-function isArtifactPath(path) {
-    return path === "/artifacts" || path.startsWith("/artifacts/");
-}
 export function operatorPageTitle(page, configuredTitle) {
     return `${OPERATOR_PAGE_LABELS[page]} — ${configuredTitle}`;
 }
-/**
- * The badge a tool earns, from the predicates core enforces with. Computed
- * here so the page reports the rule rather than restating it. `exempt` is the
- * config exemption (#566), which `isApprovalExempt` already refuses to grant
- * a read-only tool.
- */
-export function uiToolSafety(definition, exempt = false) {
-    if (isExplicitlyReadOnly(definition))
+/** Report the verdict the registry stored, independent of pool trust. */
+export function uiToolSafety(definition) {
+    if (definition.classification === "read")
         return "runs_in_programs";
-    return exempt ? "exempt" : "needs_approval";
+    return "needs_approval";
 }
 /**
  * The fix-prompt key for a connector that is not usable. Chosen from the
@@ -63,6 +54,8 @@ export function uiToolSafety(definition, exempt = false) {
 export function uiProblemFor(connector, status, observed) {
     if (observed.credentialDrift)
         return "credential_mismatch";
+    if (status === "credential_required")
+        return "credential_required";
     if (status === "error")
         return "connector_unavailable";
     if (status === "auth_required") {
@@ -86,9 +79,7 @@ export function credentialManagementCapability(input) {
  * isolated: they surface status "error" with an empty tool list rather than
  * failing the whole payload.
  */
-export async function buildUiData(registry, baseUrl, serverInfo, credentialVault, activityEnabled = false, credentialManagement = credentialVault
-    ? "available"
-    : "requires_operator", defer, oauthManagement = false, discoveryConcurrency, personalCredentialOwner, detailOptions = {}) {
+export async function buildUiData(registry, baseUrl, serverInfo, credentialVault, activityEnabled = false, credentialManagement = credentialVault ? "available" : "requires_operator", defer, oauthManagement = false, discoveryConcurrency, personalCredentialOwner, detailOptions = {}) {
     return runEdge(uiData(registry, baseUrl, {
         serverInfo,
         credentialVault,
@@ -102,27 +93,24 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
     }));
 }
 function jsonForInlineScript(value) {
-    return JSON.stringify(value)
-        .replaceAll("<", "\\u003c")
-        .replaceAll(">", "\\u003e")
-        .replaceAll("&", "\\u0026");
+    return JSON.stringify(value).replaceAll("<", "\\u003c").replaceAll(">", "\\u003e").replaceAll("&", "\\u0026");
 }
 /**
  * Every operator page serves this same data-free shell. Connector, credential,
  * and activity data arrives only through the authenticated `/ui/*` APIs.
  */
-export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "connections", options = {}) {
+export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, 
+/** @deprecated Scripts load from same-origin assets; ignored. */
+_nonce, page = "overview") {
     const clerk = uiAuth?.kind === "clerk" ? uiAuth : undefined;
     // The Clerk loader's origin. A value that fails the gate is dropped rather
     // than escaped into the page: the loader tag is simply not emitted, the gate
     // reports that Clerk could not load, and the rest of the shell still renders —
     // the same fallback-and-warn posture the branding URLs take, with the drop
     // named in a startup warning (see `droppedUiAuthUrls`).
-    const clerkScriptOrigin = clerk && isSafeHttpsUrl(clerk.frontendApiUrl)
-        ? clerk.frontendApiUrl
-        : undefined;
+    const clerkScriptOrigin = clerk && isSafeHttpsUrl(clerk.frontendApiUrl) ? clerk.frontendApiUrl : undefined;
     // Enumerated field by field, because this object is serialized into the page's
-    // inline script: a rejected frontendApiUrl must not reach the document through
+    // JSON config: a rejected frontendApiUrl must not reach the document through
     // `AUTH` after being kept out of the `<script src>`, and a rejected
     // signInUrl/signUpUrl — which `AUTH` is the only path into the page for — must
     // not reach it at all. Dropping one leaves the key absent, so `Clerk.load`
@@ -132,20 +120,13 @@ export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "c
             kind: clerk.kind,
             publishableKey: clerk.publishableKey,
             ...(clerkScriptOrigin ? { frontendApiUrl: clerkScriptOrigin } : {}),
-            ...(isSafeHttpsUrl(clerk.signInUrl)
-                ? { signInUrl: clerk.signInUrl }
-                : {}),
-            ...(isSafeHttpsUrl(clerk.signUpUrl)
-                ? { signUpUrl: clerk.signUpUrl }
-                : {}),
+            ...(isSafeHttpsUrl(clerk.signInUrl) ? { signInUrl: clerk.signInUrl } : {}),
+            ...(isSafeHttpsUrl(clerk.signUpUrl) ? { signUpUrl: clerk.signUpUrl } : {}),
         }
         : (uiAuth ?? { kind: "bearer" });
     const brand = resolveBranding(branding);
-    // When an operator shell ships a nonce-based CSP, every script it emits must
-    // carry that nonce to run; without a nonce the markup is unchanged.
-    const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
     const clerkScript = clerk && clerkScriptOrigin
-        ? `<script${nonceAttr} crossorigin="anonymous" data-clerk-publishable-key="${escapeHtml(clerk.publishableKey)}" src="${escapeHtml(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
+        ? `<script crossorigin="anonymous" data-clerk-publishable-key="${escapeHtml(clerk.publishableKey)}" src="${escapeHtml(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
         : "";
     // The shared layout owns the head, scheme, theme, and masthead; the shell
     // adds its own bundle (which already imports the shared tokens), the nav
@@ -153,9 +134,10 @@ export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "c
     return renderPage(branding, {
         title: operatorPageTitle(page, brand.pageTitle),
         uiMounted: true,
-        iconOrigin: options.iconOrigin,
-        styles: OPERATOR_UI_CSS,
-        head: clerkScript,
+        operatorShell: true,
+        styles: "",
+        head: `<link rel="stylesheet" href="${OPERATOR_UI_STYLE_PATH}"><link rel="license" href="${OPERATOR_UI_NOTICES_PATH}">` +
+            clerkScript,
         skipTo: { id: "operatorContent", label: "Skip to operator page" },
         mastheadEnd: '<div id="operatorNav"></div>',
         body: `
@@ -170,28 +152,45 @@ export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "c
   </div>
 </main>
 `,
-        tail: `<script${nonceAttr}>
-const AUTH = ${jsonForInlineScript(auth)};
-const MCP_URL = ${jsonForInlineScript(mcpUrl)};
-const INITIAL_PAGE = ${jsonForInlineScript(page)};
-const HOME_URL = ${jsonForInlineScript(options.homeUrl ?? "/")};
-const TITLE_SUFFIX = ${jsonForInlineScript(brand.pageTitle)};
-const PRODUCT_NAME = ${stringForInlineScript(brand.productName)};
-const PRODUCT_DESCRIPTION = ${stringForInlineScript(brand.description)};
-const PRODUCT_OPERATOR_LABEL = ${stringForInlineScript(brand.productName + " operator")};
-${OPERATOR_UI_SCRIPT}</script>`,
+        tail: `<script id="operatorConfig" type="application/json">${jsonForInlineScript({
+            auth,
+            mcpUrl,
+            initialPage: page,
+            titleSuffix: brand.pageTitle,
+            productName: brand.productName,
+            productDescription: brand.description,
+            productOperatorLabel: brand.productName + " operator",
+        })}</script><script defer src="${OPERATOR_UI_SCRIPT_PATH}"></script>`,
     });
 }
 function ownsOperatorPath(reserved, path) {
     if (path === "/activity" || path === "/tokens")
         return true;
-    return reserved.some((pattern) => pattern.endsWith("/*")
-        ? path.startsWith(pattern.slice(0, -1))
-        : path === pattern);
+    return reserved.some((pattern) => pattern.endsWith("/*") ? path.startsWith(pattern.slice(0, -1)) : path === pattern);
 }
+/** The closed options operatorUi() accepts; see `assertKnownOptions`. */
+const OPERATOR_UI_OPTIONS = optionsOf()({
+    branding: optionsOf()({
+        ...keys("productName", "productUrl", "ownerName", "ownerUrl", "description", "pageTitle", "themeColor"),
+        favicon: optionsOf()(keys("svg", "ico", "href")),
+        theme: optionsOf()(keys("accent", "radius", "fontFamily", "monoFamily", "colorScheme")),
+    }),
+});
 /** Mount the connection UI without enabling any storage or activity module. */
 export function operatorUi(options = {}) {
-    const reservedPaths = ["/", "/ui", "/ui/*", "/favicon.svg", "/favicon.ico"];
+    options = assertKnownOptions(options, "operatorUi()", OPERATOR_UI_OPTIONS);
+    const reservedPaths = [
+        "/",
+        "/connectors",
+        "/connectors/*",
+        "/tools",
+        "/access",
+        "/config",
+        "/ui",
+        "/ui/*",
+        "/favicon.svg",
+        "/favicon.ico",
+    ];
     return {
         ...options,
         reservedPaths,
@@ -203,25 +202,12 @@ export function operatorUi(options = {}) {
             // route here, and no activity module, runs for a path this surface does
             // not own. The Activity page is the one addition; the server reserves
             // it only when history is readable, and routeUi checks the same thing.
-            // Artifact pages are the other: they exist only beside the module.
-            const artifacts = context.opts.artifactsModule;
-            const artifactPath = Boolean(artifacts) && isArtifactPath(context.path);
-            if (!artifactPath && !ownsOperatorPath(reservedPaths, context.path))
+            if (!ownsOperatorPath(reservedPaths, context.path))
                 return null;
-            if (artifactPath && !operatorPageForPath(context.path)) {
-                // The pages' JSON API and the sandboxed frame; the module owns both,
-                // and this bundle imports none of it.
-                return (await artifacts?.handle(context)) ??
-                    notFoundResponse(context.request, context.opts);
-            }
-            const tokenResponse = await context.opts.accessTokens?.handle(context);
+            const tokenResponse = await context.opts.config.accessTokens?.handle(context);
             if (tokenResponse)
                 return tokenResponse;
-            const routes = [
-                ...(context.opts.credentialVault ? [routeCredentials] : []),
-                routeOAuthManagement,
-                routeUi,
-            ];
+            const routes = [...(context.opts.config.vault ? [routeCredentials] : []), routeOAuthManagement, routeUi];
             for (const route of routes) {
                 const response = await route(context);
                 if (response) {
@@ -234,7 +220,7 @@ export function operatorUi(options = {}) {
                     return response;
                 }
             }
-            return context.opts.activityModule?.handle(context) ?? null;
+            return context.opts.config.activity?.handle(context) ?? null;
         },
     };
 }

package/dist/url-safety.js

@@ -48,7 +48,7 @@ function ipv6Pieces(host) {
     const pieces = (part) => {
         if (!part)
             return [];
-        const parsed = part.split(":").map((piece) => HEXTET.test(piece) ? Number.parseInt(piece, 16) : Number.NaN);
+        const parsed = part.split(":").map((piece) => (HEXTET.test(piece) ? Number.parseInt(piece, 16) : Number.NaN));
         return parsed.some(Number.isNaN) ? undefined : parsed;
     };
     const head = pieces(halves[0]);
@@ -89,9 +89,7 @@ function classifyIpv6(pieces) {
 function canonicalHost(hostname) {
     if (/[/\\?#@]/.test(hostname))
         return undefined;
-    const bracketed = hostname.includes(":") && !hostname.startsWith("[")
-        ? `[${hostname}]`
-        : hostname;
+    const bracketed = hostname.includes(":") && !hostname.startsWith("[") ? `[${hostname}]` : hostname;
     try {
         return new URL(`http://${bracketed}/`).hostname;
     }
@@ -144,8 +142,7 @@ export function learnedUrlRefusal(configured, target) {
     if (target.origin === configured.origin)
         return undefined;
     const targetClass = classifyHost(target.hostname);
-    if (targetClass === "loopback" &&
-        classifyHost(configured.hostname) === "loopback") {
+    if (targetClass === "loopback" && classifyHost(configured.hostname) === "loopback") {
         return undefined;
     }
     if (targetClass !== "public") {

package/dist/usage-guide.js

@@ -0,0 +1,146 @@
+/** Self-contained content for the usage skill; independent of skill registration. */
+export const USAGE_SKILL = `---
+name: usage
+description: How to route work between one execute_code program and Connecta's explicit call, authorization, and result tools.
+---
+
+# Connecta usage
+
+## Choose the route
+
+| Work | Tool |
+| --- | --- |
+| One known-address read | call_tool |
+| One known-address write | call_destructive_tool |
+| Discovery, multiple or dependent calls, paging, reduction | execute_code |
+
+Read one account with call_tool: \`{ "address": "crm.get_account", "args": { "id": "acct_42" } }\`.
+Discover and call together when schemas suffice. search_tools covers catalog
+inspection and write discovery in read-only pools. Programs may
+write only in trusted pools; the tool description states this endpoint's trust.
+Unannotated tools fail closed to writes.
+
+## The global and the envelopes
+
+Pass JavaScript \`async () => { ... }\`, no arguments. Do not shadow \`connecta\`.
+No imports, require, filesystem, fetch, or timers.
+
+Use \`connecta.call(address, args, { timeoutMs })\` or
+\`connecta.call({ address, args, timeoutMs })\`; both return \`{ data, format }\`.
+\`format: "json"\` carries JSON; \`format: "text"\` carries text. Parse text only
+when documented as JSON. Verify collection roots.
+
+\`connecta.read("resource://id/"+encodeURIComponent(uri))\` returns \`{ contents }\` for advertised URIs.
+
+Search/describe return \`{ tools }\`, never an array. Search also returns
+\`catalogErrors\`, pagination, and possible \`absence\`; check failures before
+selecting a match. JSON schemas are the program default. Compact schemas have
+\`schemaFormat: "text"\`; do not read their .properties. Select the exact tool and
+account/environment, inspect its schema, and supply its required keys and types.
+
+Discover an unfamiliar read and reduce its result:
+
+\`\`\`js
+async () => {
+  const page = await connecta.search({ connector: "ci", query: "get_run" });
+  if (page.catalogErrors.length || page.absence) return page;
+  const tool = page.tools.find(t => t.name === "get_run");
+  if (!tool) return { gap: "get_run unavailable" };
+  const result = await connecta.call(tool.address, { runId: 42 });
+  return result.format === "json"
+    ? { status: result.data.status, jobId: result.data.failedJobId } : result;
+}
+\`\`\`
+
+## Keep partial successes
+
+Use Promise.allSettled to keep independent successes. Rejections retain \`code\`,
+\`message\`, \`retryable\`, and \`details\`. Branch on fields, not prose. Repair
+arguments before batching. Runs report hostCalls separately.
+
+Read JSON and text after verifying addresses and schemas:
+
+\`\`\`js
+async () => {
+  const settled = await Promise.allSettled([
+    connecta.call("ci.get_run", { runId: 42 }),
+    connecta.call("ci.get_job_logs", { jobId: "job_7" }),
+    connecta.call("ci.get_run", { runId: "wrong-type" })
+  ]);
+  return settled.map(s => s.status === "rejected"
+    ? { error: s.reason.code, retryable: s.reason.retryable }
+    : s.value.format === "text"
+      ? { text: s.value.data.split("\\n").filter(line => line.startsWith("ERROR")) }
+      : { status: s.value.data.status });
+}
+\`\`\`
+
+Host-call budget exhaustion ends the run with budget_exceeded. Catch and
+allSettled cannot recover it or return partial output. Bound batches before
+starting them; search, describe, call, result, and skill spend host calls.
+Split remaining reads. Never replay writes for their output.
+
+## Per-connector guides
+
+Fetch a listed guide with skills by its exact name, or \`connecta.skill(name)\`
+inside a program; it returns \`{ name, text, format: "text" }\`.
+\`guideRequired: true\` is a hard stop. connector_required and approval_required
+remain after schema expansion; schema_truncated clears after exact describe.
+Otherwise fetch for units, pagination, aliases, or sequences.
+
+## Large results and recovery
+
+Large direct results and program returns carry resultId when paging is available. Follow
+nextOffset in UTF-8 bytes, reassemble and reduce inside one program. Use the
+returned id in place of result-id below; this example assumes documented JSON.
+
+Calls reconstruct up to 1 MiB through stash pages. Larger values return
+\`{ format: "paged", valueFormat, resultId?, totalBytes, hint }\`. Pass the handle
+to \`connecta.result\`. No resultId means no paging. IDs expire after
+15 minutes; only explicit paging spends extra host calls.
+Use zero-based \`{ page: 0 }\` or UTF-8 \`{ offset }\`, never both. Keep maxBytes
+fixed across pages; connector caps and the 32 KiB bridge ceiling apply.
+
+\`\`\`js
+async () => {
+  let text = "", offset = 0, page;
+  do {
+    page = await connecta.result("result-id", { offset, maxBytes: 8000 });
+    text += page.text;
+    offset = page.nextOffset;
+  } while (page.hasMore);
+  return JSON.parse(text).items.map(item => item.id);
+}
+\`\`\`
+
+Oversized returns lead with nextAction. Never rerun writes for output. write_outcome_unknown forbids retry, even if caught.
+Recovery args may be partial (argsRedacted) or absent (argsOmitted). Reconcile
+before retrying with the original args or repeating a program that sent writes.
+Non-retryable errors need repair.
+host_auth_required needs host connection repair; provider_permission_denied needs
+resource-owner access. Auth failures carry the handoff in error.data. When an auth
+error includes a handoff, give it to the user or operator.
+
+## Output
+
+Use \`connecta.emit(await connecta.call(address, args))\` for MCP rich output,
+or \`for (const b of x.content ?? []) connecta.emit(b)\`. Both forward originals,
+including resources and metadata; edits do not change them. Page oversized
+native content with \`connecta.result(x.contentResult)\`.
+Authored blocks accept text or base64 image/audio; images require canonical
+base64 and PNG/JPEG/GIF/WebP MIME. Emit works without await, delivers on success,
+and obeys byte/block budgets; text shares the return cap. Return reduced JSON.
+
+`;
+/** Kept in sync with GuestApi by the declaration test. These are type notation, not runnable JS. */
+export const GUEST_API_DECLARATION = `search(args?: CatalogSearchArgs): Promise<CatalogSearchResult>;
+describe(args?: CatalogDescribeArgs): Promise<{ tools: CatalogDescription[] }>;
+call(address: string, args?: unknown, options?: { timeoutMs?: number }): Promise<GuestResult>;
+call(request: { address: string; args?: unknown; timeoutMs?: number }): Promise<GuestResult>;
+read(uri: string): Promise<GuestResourceResult>;
+result(
+  id: string | GuestResultHandle,
+  options?: { page?: number; offset?: number; maxBytes?: number },
+): Promise<GuestResultPage>;
+skill(name: string): Promise<{ name: string; text: string; format: "text" }>;
+emit(block: GuestNativeBlock | GuestResult): PromiseLike<void>;`;

package/dist/validate.d.ts

@@ -1,4 +1,5 @@
 import { ConnectorCallError } from "./errors.js";
+import { type FailureSubject } from "./operator-record.js";
 import type { JsonSchema, Logger } from "./types.js";
 export interface ValidateToolInputOptions {
     /**
@@ -54,6 +55,12 @@ export interface CompileValidatorOptions {
  * the `Connector` interface directly.
  */
 export declare function validateToolInput(schema: JsonSchema, args: unknown, opts: ValidateToolInputOptions): ConnectorCallError | null;
+/**
+ * `validateToolInput` for a tool connecta resolved in a catalog. `subject`
+ * names it in the log record when the schema is unusable; a caller's own
+ * address never reaches the log.
+ */
+export declare function validateCatalogToolInput(schema: JsonSchema, args: unknown, opts: ValidateToolInputOptions, subject: FailureSubject): ConnectorCallError | null;
 /**
  * Eagerly compile and cache a tool's inputSchema, throwing when the validator
  * cannot use it. Reuses the same module-level cache `validateToolInput` reads,