@zackbart/connecta 0.25.0 → 0.26.1

package/dist/tool-safety.d.ts

@@ -0,0 +1,35 @@
+import type { Connector, ToolDef } from "./types.js";
+/**
+ * The one fail-closed classification shared by discovery and invocation.
+ *
+ * A tool is read-only only when it says so without also saying it is
+ * destructive. Missing, false, and contradictory annotations all require the
+ * approval-visible call path.
+ */
+export declare function isExplicitlyReadOnly(definition: ToolDef): boolean;
+/**
+ * A deployment's approval exemptions, resolved once at construction from
+ * `execute.approval` (#566). Config is the only source: nothing an agent, the
+ * operator UI, or a downstream catalog says can add an entry.
+ */
+export interface ApprovalPolicy {
+    /** Connector id → the default for that connector's tools. */
+    readonly connectors: ReadonlyMap<string, "never" | "ask">;
+    /** Canonical `connector.tool` address → that tool's own setting. */
+    readonly tools: ReadonlyMap<string, "never" | "ask">;
+}
+export declare const NO_EXEMPTIONS: ApprovalPolicy;
+/**
+ * Whether a program may call this tool without pausing for approval.
+ *
+ * Only a tool that is *not* explicitly read-only can be exempt — a read-only
+ * tool needs no exemption, and reporting one would blur the two classes an
+ * exemption must never merge. The most specific setting wins: the tool's
+ * address, then its connector's entry, then the connector's own default,
+ * then `"ask"`. Annotations play no part beyond that first test: a downstream
+ * that could annotate its way out of approval would be granting itself the
+ * capability this exists to keep in config. Exempt never means read-only:
+ * discovery keeps it in the approval-required class, and `call_tool` still
+ * refuses it.
+ */
+export declare function isApprovalExempt(policy: ApprovalPolicy, connector: Pick<Connector, "id" | "approval">, toolName: string, definition: ToolDef): boolean;

package/dist/tool-safety.js

@@ -9,3 +9,34 @@ export function isExplicitlyReadOnly(definition) {
     return (definition.annotations?.readOnlyHint === true &&
         definition.annotations?.destructiveHint !== true);
 }
+export const NO_EXEMPTIONS = {
+    connectors: new Map(),
+    tools: new Map(),
+};
+/**
+ * Whether a program may call this tool without pausing for approval.
+ *
+ * Only a tool that is *not* explicitly read-only can be exempt — a read-only
+ * tool needs no exemption, and reporting one would blur the two classes an
+ * exemption must never merge. The most specific setting wins: the tool's
+ * address, then its connector's entry, then the connector's own default,
+ * then `"ask"`. Annotations play no part beyond that first test: a downstream
+ * that could annotate its way out of approval would be granting itself the
+ * capability this exists to keep in config. Exempt never means read-only:
+ * discovery keeps it in the approval-required class, and `call_tool` still
+ * refuses it.
+ */
+export function isApprovalExempt(policy, connector, toolName, definition) {
+    if (isExplicitlyReadOnly(definition))
+        return false;
+    // This tool starts another program. Letting a program call it while holding
+    // the only executor permit would deadlock; manual refresh is a top-level
+    // action, even though other artifact writes are exempt inside programs.
+    if (connector.id === "artifacts" && toolName === "run_refresh")
+        return false;
+    const setting = policy.tools.get(`${connector.id}.${toolName}`) ??
+        policy.connectors.get(connector.id) ??
+        connector.approval ??
+        "ask";
+    return setting === "never";
+}

package/dist/types.d.ts

@@ -149,6 +149,11 @@ export interface ConnectorCredentialConfig {
 }
 export interface CredentialTestResult {
     ok: boolean;
+    /**
+     * Detail for the deployment's log. The operator page shows fixed copy for
+     * `ok` and never this text, since a downstream's reply quoted here can
+     * quote the credential it rejected.
+     */
     message?: string;
 }
 export interface ConnectorContext {
@@ -212,6 +217,11 @@ export interface ConnectorStatus {
     state: ConnectorStatusState;
     /** When state === "auth_required", the URL the operator should open. */
     authorizationUrl?: string;
+    /**
+     * Set by a non-forced `startAuth` that handed back a still-recent pending
+     * authorization URL instead of starting a new flow. Absent otherwise.
+     */
+    authorizationReused?: boolean;
     message?: string;
     /**
      * Drift observed the last time this connector served a catalog refresh *in
@@ -240,6 +250,17 @@ export interface Connector {
     title?: string;
     /** How call_tool wraps results. "mcp" passes the content array through; anything else is JSON-wrapped. */
     kind?: "mcp" | "api";
+    /**
+     * This connector's own default for its tools that are not explicitly
+     * read-only, inside `execute_code`: `"never"` lets a program call them
+     * without pausing for approval. Reserved for connectors connecta ships
+     * whose writes are cheap to undo (the planned artifacts connector, whose
+     * every write is a new immutable version); a deployment's own connectors
+     * leave it unset and exempt through `execute.approval`, which overrides
+     * this either way. Never read from a downstream catalog — a server cannot
+     * exempt its own tools — and never makes a tool read-only anywhere else.
+     */
+    approval?: "never";
     description?: string;
     /**
      * Max inline result size (bytes) for this connector's tools before
@@ -394,6 +415,8 @@ export interface AdmissionSnapshot {
     maxQueueSize: number;
     queueTimeoutMs: number;
     retryAfterMs: number;
+    /** Hard admitted-request lifetime, present only on the /mcp pool. */
+    maxDurationMs?: number;
     active: number;
     queued: number;
     closed: boolean;

package/dist/ui.d.ts

@@ -2,18 +2,21 @@ import type { OperatorSurface } from "./module-contracts.js";
 import type { CredentialVault } from "./credential-contract.js";
 import { type DeferredWork } from "./connector-scope.js";
 import { type CredentialManagementCapability, type UiData, type UiProblem, type UiToolSafety } from "./operator-ui/model.js";
+import { type ApprovalPolicy } from "./tool-safety.js";
 import type { RegistryView } from "./registry.js";
 import type { ConnectaBranding, Connector, ConnectorStatus, ToolDef, UiAuthConfig } from "./types.js";
 export { filterUiConnectors, type CredentialManagementCapability, type UiConnector, type UiData, } from "./operator-ui/model.js";
 export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, isSafeIconHref } from "./branding.js";
-export type OperatorPage = "connections" | "activity";
+export type OperatorPage = "connections" | "activity" | "artifacts" | "artifact";
 export declare function operatorPageForPath(path: string): OperatorPage | undefined;
 export declare function operatorPageTitle(page: OperatorPage, configuredTitle: string): string;
 /**
- * The badge a tool earns, from the one predicate core enforces with. Computed
- * here so the page reports the rule rather than restating it.
+ * 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 declare function uiToolSafety(definition: ToolDef): UiToolSafety;
+export declare function uiToolSafety(definition: ToolDef, exempt?: boolean): UiToolSafety;
 /**
  * The fix-prompt key for a connector that is not usable. Chosen from the
  * status state and the connector's declared auth shape — configuration, never
@@ -40,12 +43,21 @@ export declare function buildUiData(registry: RegistryView, baseUrl: string, ser
     mayManage?: (id: string) => boolean;
     timeoutMs?: number;
     signal?: AbortSignal;
+    approval?: ApprovalPolicy;
 }): Promise<UiData>;
 /**
  * Every operator page serves this same data-free shell. Connector, credential,
  * and activity data arrives only through the authenticated `/ui/*` APIs.
  */
-export declare function renderUiHtml(uiAuth?: UiAuthConfig, mcpUrl?: string, branding?: ConnectaBranding, nonce?: string, page?: OperatorPage): string;
+export declare function renderUiHtml(uiAuth?: UiAuthConfig, mcpUrl?: string, branding?: ConnectaBranding, nonce?: string, page?: OperatorPage, options?: {
+    /** Where the Connections page lives, when this shell is on another origin. */
+    homeUrl?: string;
+    /**
+     * The origin that serves `/favicon.*`, when this shell is on another one:
+     * an artifact host answers those paths with 404. See `PageLayout.iconOrigin`.
+     */
+    iconOrigin?: string | undefined;
+}): string;
 /** Mount the connection UI without enabling any storage or activity module. */
 export declare function operatorUi(options?: {
     branding?: ConnectaBranding;

package/dist/ui.js

@@ -6,7 +6,7 @@ import { runEdge } from "./runtime/run.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
 import { OPERATOR_UI_CSS, OPERATOR_UI_SCRIPT, } from "./operator-ui/generated.js";
 export { filterUiConnectors, } from "./operator-ui/model.js";
-import { resolveBranding, isSafeHttpsUrl, themeCss } from "./branding.js";
+import { escapeHtml, isSafeHttpsUrl, notFoundResponse, 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
@@ -18,23 +18,39 @@ function stringForInlineScript(value) {
 const OPERATOR_PAGE_LABELS = {
     connections: "Connections",
     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 === "/")
         return "connections";
     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 one predicate core enforces with. Computed
- * here so the page reports the rule rather than restating it.
+ * 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) {
-    return isExplicitlyReadOnly(definition) ? "runs_in_programs" : "needs_approval";
+export function uiToolSafety(definition, exempt = false) {
+    if (isExplicitlyReadOnly(definition))
+        return "runs_in_programs";
+    return exempt ? "exempt" : "needs_approval";
 }
 /**
  * The fix-prompt key for a connector that is not usable. Chosen from the
@@ -82,13 +98,6 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
         ...detailOptions,
     }));
 }
-function escapeHtmlAttr(value) {
-    return value
-        .replaceAll("&", "&amp;")
-        .replaceAll('"', "&quot;")
-        .replaceAll("<", "&lt;")
-        .replaceAll(">", "&gt;");
-}
 function jsonForInlineScript(value) {
     return JSON.stringify(value)
         .replaceAll("<", "\\u003c")
@@ -99,7 +108,7 @@ function jsonForInlineScript(value) {
  * 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") {
+export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "connections", options = {}) {
     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
@@ -129,81 +138,46 @@ export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "c
         }
         : (uiAuth ?? { kind: "bearer" });
     const brand = resolveBranding(branding);
-    const title = operatorPageTitle(page, brand.pageTitle);
     // 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}"` : "";
-    // 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 owner = brand.ownerName
-        ? brand.ownerUrl
-            ? `<a class="brand navlink" href="${escapeHtmlAttr(brand.ownerUrl)}">${escapeHtmlAttr(brand.ownerName)}</a>`
-            : `<span class="brand">${escapeHtmlAttr(brand.ownerName)}</span>`
-        : brand.productUrl
-            ? `<a class="brand navlink" href="${escapeHtmlAttr(brand.productUrl)}">${escapeHtmlAttr(brand.productName)}</a>`
-            : `<span class="brand">${escapeHtmlAttr(brand.productName)}</span>`;
-    const product = brand.ownerName
-        ? brand.productUrl
-            ? `<a class="product navlink" href="${escapeHtmlAttr(brand.productUrl)}">${escapeHtmlAttr(brand.productName)}</a>`
-            : `<span class="product">${escapeHtmlAttr(brand.productName)}</span>`
-        : "";
     const clerkScript = clerk && clerkScriptOrigin
-        ? `<script${nonceAttr} crossorigin="anonymous" data-clerk-publishable-key="${escapeHtmlAttr(clerk.publishableKey)}" src="${escapeHtmlAttr(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
+        ? `<script${nonceAttr} crossorigin="anonymous" data-clerk-publishable-key="${escapeHtml(clerk.publishableKey)}" src="${escapeHtml(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
         : "";
-    // A pinned scheme is an attribute, not a stylesheet edit: the dark palette
-    // keys off `html[data-scheme]`, so "system" leaves the attribute off and the
-    // media query decides.
-    const schemeAttr = brand.theme.colorScheme === "system"
-        ? ""
-        : ` data-scheme="${brand.theme.colorScheme}"`;
-    return `<!doctype html>
-<html lang="en"${schemeAttr}>
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="theme-color" content="${escapeHtmlAttr(brand.themeColor)}">
-<meta name="description" content="${escapeHtmlAttr(brand.description)}">
-<link rel="icon" href="${escapeHtmlAttr(brand.faviconHref)}" type="image/svg+xml">
-<link rel="shortcut icon" href="/favicon.ico">
-<title>${escapeHtmlAttr(title)}</title>
-${clerkScript}
-<style>${OPERATOR_UI_CSS}${themeCss(brand.theme)}</style>
-</head>
-<body>
-<a class="skip-link" href="#operatorContent">Skip to operator page</a>
-<header class="masthead shell">
-  <div class="masthead-inner">
-    <div class="mast-nav">
-      ${owner}
-      ${product}
-    </div>
-    <div id="operatorNav"></div>
-  </div>
-</header>
-
+    // The shared layout owns the head, scheme, theme, and masthead; the shell
+    // adds its own bundle (which already imports the shared tokens), the nav
+    // mount, and the app.
+    return renderPage(branding, {
+        title: operatorPageTitle(page, brand.pageTitle),
+        uiMounted: true,
+        iconOrigin: options.iconOrigin,
+        styles: OPERATOR_UI_CSS,
+        head: clerkScript,
+        skipTo: { id: "operatorContent", label: "Skip to operator page" },
+        mastheadEnd: '<div id="operatorNav"></div>',
+        body: `
 <main id="operatorContent" class="page shell" tabindex="-1">
   <div class="lead">
     <h1>${OPERATOR_PAGE_LABELS[page]}</h1>
     <div class="lead-copy">
-      <p>${escapeHtmlAttr(brand.description)}</p>
+      <p>${escapeHtml(brand.description)}</p>
       <noscript><p class="msg">The operator pages need JavaScript. Nothing else here
       does — agents reach this deployment through <span class="mono">/mcp</span>.</p></noscript>
     </div>
   </div>
 </main>
-
-<script${nonceAttr}>
+`,
+        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>
-</body>
-</html>`;
+${OPERATOR_UI_SCRIPT}</script>`,
+    });
 }
 function ownsOperatorPath(reserved, path) {
     if (path === "/activity")
@@ -226,8 +200,17 @@ 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.
-            if (!ownsOperatorPath(reservedPaths, context.path))
+            // 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))
                 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 routes = [
                 ...(context.opts.credentialVault ? [routeCredentials] : []),
                 routeOAuthManagement,

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.25.0";
+export declare const CONNECTA_VERSION = "0.26.1";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.25.0";
+export const CONNECTA_VERSION = "0.26.1";