@zackbart/connecta 0.33.0 → 0.34.1

package/dist/config.js

@@ -184,6 +184,31 @@ function assertFlag(value, path) {
     if (typeof value !== "boolean")
         throw new ConfigError(`${path} must be true or false.`);
 }
+/** Longest pool `description`, in characters, after trimming. */
+const MAX_POOL_DESCRIPTION_LENGTH = 500;
+/**
+ * A pool description is one line of prose for the model. C0 and C1 controls
+ * (including NEL), plus Unicode line and paragraph separators, are refused.
+ * A scan, as in remote-mcp.ts,
+ * because a character class over the control range trips `no-control-regex`.
+ */
+function hasLineBreakOrControlCharacter(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f) || code === 0x2028 || code === 0x2029)
+            return true;
+    }
+    return false;
+}
+function assertPoolDescription(value, path) {
+    const trimmed = typeof value === "string" ? value.trim() : undefined;
+    if (trimmed === undefined ||
+        trimmed.length === 0 ||
+        [...trimmed].length > MAX_POOL_DESCRIPTION_LENGTH ||
+        hasLineBreakOrControlCharacter(trimmed)) {
+        throw new ConfigError(`${path} must be text of 1 to ${MAX_POOL_DESCRIPTION_LENGTH} characters after trimming, with no line breaks or control characters.`);
+    }
+}
 /** Shape only; each reference resolves against auth and agents in createConnecta. */
 function assertMemberList(value, path) {
     if (!Array.isArray(value)) {
@@ -217,8 +242,9 @@ const pool = {
      * The Google Workspace address agents in this pool act as, on a Workspace
      * connector whose `subject` is a mapping function. Humans always act as
      * themselves through that mapping, and a fixed `subject` address applies to
-     * everyone. Without an owner, an agent's Workspace calls fail
-     * `auth_required`.
+     * everyone. Without an owner, a mapping-subject Workspace connector is
+     * absent for this pool's agents, as a personal connector is; people in the
+     * pool still see it.
      */
     owner: opaque({
         check: (value, path) => {
@@ -227,6 +253,14 @@ const pool = {
             }
         },
     }),
+    /**
+     * What this pool is for, in plain words for the model: appended to the MCP
+     * `initialize` instructions at `/mcp/<name>` and `/agent/<name>`, so a
+     * caller learns its scope ("Team tier: shared tools only."). Trimmed, 1 to
+     * 500 characters, no line breaks or control characters. It grants and hides nothing; plain
+     * `/mcp` never shows it.
+     */
+    description: opaque({ check: assertPoolDescription }),
 };
 const icon = {
     src: required(text()),

package/dist/connector-caller.js

@@ -9,7 +9,8 @@
 //   Workspace through domain-wide delegation (`src/providers/_shared/google/`) — which
 //   hand the identity to a deployment-config function that names the
 //   downstream subject (PRINCIPLES.md INV-3, #678), or, for an agent, use the
-//   admitted pool's configured owner (decisions/0006). The provider never
+//   admitted pool's configured owner (decisions/0006), and the scoped registry
+//   view hides the connector from an agent whose pool has none. The provider never
 //   decides whose account to open; config does, from this.
 //
 // Core sets it from the authorization that admitted the request, on the scoped

package/dist/connectors/api-connector.d.ts

@@ -112,6 +112,8 @@ export interface ApiOptions {
      * construct.
      */
     maxResultBytes?: number;
+    /** Serve only read-classified tools on every endpoint. Defaults to false. */
+    readOnly?: boolean;
     /** Optional per-runtime downstream call-admission policy. */
     callAdmission?: ConnectorCallAdmissionPolicy;
     /**
@@ -146,6 +148,7 @@ export interface ApiOptions {
 /** The closed options api() accepts; see `assertKnownOptions`. */
 export declare const API_OPTIONS: import("../config-schema.js").Field<unknown, unknown, true> & {
     readonly shape: {
+        readOnly: import("../config-schema.js").Field<boolean, boolean | undefined, true>;
         callAdmission: Omit<import("../config-schema.js").Field<unknown, ConnectorCallAdmissionPolicy | undefined, true>, "parse"> & {
             parse(value: unknown, path: string): ConnectorCallAdmissionPolicy;
             readonly shape: import("../config-schema.js").Shape & {

package/dist/connectors/api-connector.js

@@ -3,7 +3,7 @@ import { attachFailureFacts, carryFailureFacts, errorLabel } from "../operator-r
 import { compileValidator, validateCatalogToolInput } from "../validate.js";
 import { array, assertKnownOptions, instance, keys, optionsOf, strings } from "../config-schema.js";
 import { describedEndpoint, describedOrigin, describedTools } from "../described.js";
-import { CALL_ADMISSION, CREDENTIAL, USAGE_GUIDE } from "./option-shapes.js";
+import { READ_ONLY, CALL_ADMISSION, CREDENTIAL, USAGE_GUIDE } from "./option-shapes.js";
 import { assertStaticToolNames } from "../tool-name.js";
 import { registerInvocationAuth } from "../invocation-auth.js";
 import { redactCatalog, redactSentSecrets, sentSecretsFetch, trackCredentialReads } from "../sent-secrets.js";
@@ -41,6 +41,7 @@ function checkToolContract(id, tool) {
 /** The closed options api() accepts; see `assertKnownOptions`. */
 export const API_OPTIONS = optionsOf()({
     ...keys("title", "description", "authScope", "maxResultBytes", "testCredential", "testCredentials", "validateArgs"),
+    readOnly: READ_ONLY,
     callAdmission: CALL_ADMISSION,
     usageGuide: USAGE_GUIDE,
     credential: CREDENTIAL,
@@ -90,6 +91,8 @@ function describedApiAuth(opts) {
  */
 export function apiConnector(id, opts, oauth) {
     opts = assertKnownOptions(opts, `api(${JSON.stringify(id)})`, API_OPTIONS);
+    if (opts.readOnly !== undefined)
+        READ_ONLY.parse(opts.readOnly, `Connector(${JSON.stringify(id)}).readOnly`);
     if (opts.callAdmission !== undefined)
         CALL_ADMISSION.parse(opts.callAdmission, `api(${JSON.stringify(id)}).callAdmission`);
     assertStaticToolNames(opts.tools, `api(${JSON.stringify(id)}).tools`);
@@ -124,6 +127,7 @@ export function apiConnector(id, opts, oauth) {
         ...defined({
             description: opts.description,
             authScope: opts.authScope,
+            readOnly: opts.readOnly,
             maxResultBytes: opts.maxResultBytes,
             callAdmission: opts.callAdmission,
             usageGuide: opts.usageGuide,

package/dist/connectors/option-shapes.js

@@ -5,7 +5,7 @@
 // path instead of silently doing nothing (INV-11). Values stay the factory's
 // to validate; handlers, schemas, and loggers pass through as `opaque()`.
 import { array, keys, optionsOf, strings, variants } from "../config-schema.js";
-export { CALL_ADMISSION, PROVIDER_COMMON } from "../provider.js";
+export { READ_ONLY, CALL_ADMISSION, PROVIDER_COMMON } from "../provider.js";
 export const CREDENTIAL = optionsOf()({
     ...keys("label", "description", "placeholder"),
     fields: array(optionsOf()(keys("name", "label", "description", "placeholder", "inputType"))),

package/dist/connectors/remote-mcp.d.ts

@@ -82,6 +82,8 @@ export interface RemoteMcpOptions {
      * construct.
      */
     maxResultBytes?: number;
+    /** Serve only read-classified tools on every endpoint. Defaults to false. */
+    readOnly?: boolean;
     /** Optional per-runtime downstream call-admission policy. */
     callAdmission?: ConnectorCallAdmissionPolicy;
     /**

package/dist/connectors/remote-mcp.js

@@ -24,7 +24,7 @@ import { retryAfterMs } from "./guarded-fetch.js";
 import { resourceUriMatchesTemplates } from "./resource-uri.js";
 import { callerOf } from "../connector-caller.js";
 import { readNegotiation, storeNegotiation } from "./negotiation-cache.js";
-import { CALL_ADMISSION, REMOTE_MCP_AUTH, USAGE_GUIDE } from "./option-shapes.js";
+import { READ_ONLY, CALL_ADMISSION, REMOTE_MCP_AUTH, USAGE_GUIDE } from "./option-shapes.js";
 /**
  * Apply a maintained provider's slot copy and header framing to credential
  * auth the deployment left bare.
@@ -46,6 +46,7 @@ export function withCredentialDefaults(auth, defaults) {
 /** The closed options remoteMcp() accepts; see `assertKnownOptions`. */
 const REMOTE_MCP_OPTIONS = optionsOf()({
     ...keys("url", "title", "description", "authScope", "maxResultBytes", "versionNegotiation", "redirects", "requireHttps", "logger", "_transportFactory", "classify", "skills"),
+    readOnly: READ_ONLY,
     callAdmission: CALL_ADMISSION,
     usageGuide: USAGE_GUIDE,
     auth: REMOTE_MCP_AUTH,
@@ -1024,6 +1025,8 @@ function registrationErrorCode(body) {
  */
 export function remoteMcp(id, opts) {
     opts = assertKnownOptions(opts, `remoteMcp(${JSON.stringify(id)})`, REMOTE_MCP_OPTIONS);
+    if (opts.readOnly !== undefined)
+        READ_ONLY.parse(opts.readOnly, `Connector(${JSON.stringify(id)}).readOnly`);
     if (opts.callAdmission !== undefined)
         CALL_ADMISSION.parse(opts.callAdmission, `remoteMcp(${JSON.stringify(id)}).callAdmission`);
     const skillsEnabled = opts.skills;
@@ -2194,6 +2197,7 @@ export function remoteMcp(id, opts) {
             },
         }),
         ...(opts.description !== undefined ? { description: opts.description } : {}),
+        ...(opts.readOnly !== undefined ? { readOnly: opts.readOnly } : {}),
         ...(opts.authScope !== undefined ? { authScope: opts.authScope } : {}),
         ...(opts.maxResultBytes !== undefined ? { maxResultBytes: opts.maxResultBytes } : {}),
         ...(opts.callAdmission !== undefined ? { callAdmission: opts.callAdmission } : {}),

package/dist/describe-config.d.ts

@@ -20,6 +20,8 @@ export type DescribedMember = {
 };
 /** One connector as `describeConfig()` reports it. */
 export interface DescribedConnector {
+    /** Connector policy, independent of endpoint policy; omitted when false. */
+    readOnly?: boolean;
     id: string;
     title?: string;
     description?: string;
@@ -115,7 +117,8 @@ export interface ConnectaConfigDescription {
     /**
      * `readOnly` is resolved: the pool's own value, else the deployment's.
      * `members` are resolved references in declaration order. `owner` is the
-     * Workspace address agents act as, or null.
+     * Workspace address agents act as, or null. `description` is the trimmed
+     * text the pool's endpoints add to their MCP instructions, or null.
      */
     pools: Array<{
         name: string;
@@ -124,6 +127,7 @@ export interface ConnectaConfigDescription {
         members: DescribedMember[];
         readOnly: boolean;
         owner: string | null;
+        description: string | null;
     }>;
     modules: {
         ui: {

package/dist/describe-config.js

@@ -133,6 +133,7 @@ function describeConnector(connector, deploymentCap, registry) {
     const guideSummary = connectorGuideSummary(connector);
     const guided = connector.usageGuide !== undefined;
     return {
+        ...(connector.readOnly === true ? { readOnly: true } : {}),
         id: connector.id,
         ...(str(connector.title) !== undefined ? { title: connector.title } : {}),
         ...(str(connector.description) !== undefined ? { description: connector.description } : {}),
@@ -250,6 +251,7 @@ export function describeConfig(input) {
                 ? { kind: "agent", name: member.name }
                 : { kind: "human", namespace: member.namespace, id: member.id }),
             owner: input.pools.get(name)?.owner ?? null,
+            description: input.pools.get(name)?.description ?? null,
         })),
         modules: {
             ui: { enabled: config.ui !== undefined },

package/dist/execute.js

@@ -798,18 +798,8 @@ function sandboxProvider(registry, baseUrl, activity, limits, requestScope = {})
                 ...args,
                 includeSchemas: args.includeSchemas ?? "json",
                 includeSchemaKeys: args.includeSchemaKeys !== false,
-            }));
+            }, catalogDependency));
             boundedDiscoveryText(result, "Request a smaller limit, omit fullDescriptions, use compact schemas, or pass includeSchemaKeys: false.");
-            for (const tool of result.tools)
-                catalogAddressDependency(tool.address);
-            for (const error of result.catalogErrors)
-                catalogDependency(error.connector);
-            for (const connector of result.absence?.configuredConnectors ?? [])
-                catalogDependency(connector);
-            for (const connector of result.queryAnalysis?.configuredConnectors ?? [])
-                catalogDependency(connector);
-            if (result.queryAnalysis?.connectorScope)
-                catalogDependency(result.queryAnalysis.connectorScope);
             return result;
         }),
         describe: (raw) => discovery("describe", async () => {

package/dist/fix-prompt.js

@@ -29,7 +29,7 @@ export function renderFixPrompt(spec, connectorId) {
             "own logs (lines prefixed [connecta]) or by reproducing the failure locally. Never put a secret in source, " +
             "a log line, or your reply: secrets belong in the deployment's environment or its credential vault.",
         "Make the smallest change that fixes it, then verify it by redeploying and refreshing the connection on the " +
-            "operator Connections page. If the fix needs something you cannot do yourself — a provider console setting, " +
-            "a secret only the operator holds — name that exact step instead.",
+            "operator Connectors page. If the fix needs a step you cannot do yourself, such as a provider console setting " +
+            "or a secret only the operator holds, name that exact step instead.",
     ].join("\n\n");
 }

package/dist/index.js

@@ -67,6 +67,7 @@ function resolvePools(pools, readOnly, registry, members) {
             readOnly: pool.readOnly ?? readOnly,
             members: Object.freeze(resolveMembers(pool.members, path, members)),
             ...(pool.owner !== undefined ? { owner: pool.owner.trim() } : {}),
+            ...(pool.description !== undefined ? { description: pool.description.trim() } : {}),
         }));
     }
     return resolved;

package/dist/invocation.js

@@ -464,9 +464,10 @@ export class InvocationService {
                         reconciliationRequired: true,
                     };
                 }
-                const refusal = writeRefusal(target.definition.classification, context.source, context.readOnly);
+                const connectorReadOnly = target.connector.readOnly === true;
+                const refusal = writeRefusal(target.definition.classification, context.source, context.readOnly || connectorReadOnly);
                 if (refusal === "read_only_endpoint") {
-                    return framingError("read_only_endpoint", `Tool "${canonicalAddress}" is a write, and this endpoint is read-only. Nothing here can send it.`);
+                    return framingError("read_only_endpoint", `Tool "${canonicalAddress}" is a write, and ${connectorReadOnly ? `connector "${target.connector.id}"` : "this endpoint"} is read-only. Nothing here can send it.`);
                 }
                 if (refusal === "destructive_tool_requires_approval") {
                     return framingError("destructive_tool_requires_approval", `Tool "${canonicalAddress}" is a write. Invoke it through call_destructive_tool so the MCP host can request approval.`);

package/dist/membership.d.ts

@@ -25,6 +25,8 @@ export interface ResolvedPool {
     members: readonly Member[];
     /** Trimmed `owner`: the Workspace address agents in this pool act as. */
     owner?: string;
+    /** Trimmed `description`, appended to this pool's MCP instructions. */
+    description?: string;
 }
 /** What resolving a reference needs to know about the deployment. */
 export interface MemberContext {

package/dist/meta-tools.js

@@ -796,14 +796,15 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                                 return false;
                             continue;
                         }
-                        if (!registry.getConnector(dependency.connector))
+                        const connector = registry.getConnector(dependency.connector);
+                        if (!connector)
                             return false;
                         const tools = await registry.getTools(dependency.connector, baseUrl, requestScope, options.signal ? { signal: options.signal } : {});
                         const tool = tools.find((tool) => tool.name === dependency.tool);
                         if (!tool ||
                             !(dependency.access === "catalog" ||
                                 (dependency.classification === "read" && tool.classification === "read") ||
-                                opts.readOnly !== true))
+                                (opts.readOnly !== true && connector.readOnly !== true)))
                             return false;
                     }
                     return true;

package/dist/oauth-callback-outcome.js

@@ -11,7 +11,7 @@ const OUTCOMES = {
         status: 400,
         tone: "declined",
         heading: "Authorization was declined",
-        message: "Consent was declined at the provider, so nothing was stored. Start authorization again whenever you are ready.",
+        message: "Consent was declined, so nothing was stored. Start again when ready.",
         fix: {
             problem: "Consent for a downstream OAuth connector was declined at the provider, so no grant was stored.",
             steps: [
@@ -72,7 +72,7 @@ const OUTCOMES = {
         fix: {
             problem: "A provider returned an authorization code, but exchanging it for tokens failed.",
             steps: [
-                "Check the OAuth client credentials the connector uses — client id and secret in the deployment's environment — and that they belong to the same OAuth app that showed the consent screen.",
+                "Check the OAuth client id and secret the connector reads from the deployment's environment, and that they belong to the OAuth app that showed the consent screen.",
                 "Check that the token endpoint and redirect URI the connector uses match the provider's registration exactly.",
                 "Find the [connecta] warning for this callback in the deployment logs; it records the exchange error the page withholds.",
             ],

package/dist/operator-ui/agents.d.ts

@@ -62,7 +62,7 @@ export declare function slotBadge(slot: Pick<AgentSlot, "state">): {
     label: string;
     tone: Tone;
 };
-/** When the slot last changed, as "Issued <date>" or "Revoked <date>"; a dash when it never has. */
+/** When the slot last changed, issued or revoked (its badge says which); a dash when it never has. */
 export declare function slotSince(slot: AgentSlot, format: (value: string) => string): string;
 export declare function lastSeenLabel(lastSeenAt: string | null, format: (value: string) => string): string;
 /**

package/dist/operator-ui/agents.js

@@ -1,6 +1,6 @@
 import { failure } from "./view.js";
 /** Why a row's controls are disabled when its slot is not in the live list. */
-const SLOT_UNAVAILABLE = "Token state unavailable, refresh";
+const SLOT_UNAVAILABLE = "Token state unknown. Refresh.";
 /** Why a row's controls are disabled until a fresh list read resolves its slot. */
 const SLOT_UNRESOLVED = "Refresh to continue";
 export function slotActions(slot) {
@@ -53,12 +53,12 @@ export function slotBadge(slot) {
         return { label: "Revoked", tone: "warn" };
     return { label: "No token", tone: "neutral" };
 }
-/** When the slot last changed, as "Issued <date>" or "Revoked <date>"; a dash when it never has. */
+/** When the slot last changed, issued or revoked (its badge says which); a dash when it never has. */
 export function slotSince(slot, format) {
     if (slot.state === "issued")
-        return `Issued ${format(slot.issuedAt)}`;
+        return format(slot.issuedAt);
     if (slot.state === "revoked")
-        return `Revoked ${format(slot.revokedAt)}`;
+        return format(slot.revokedAt);
     return "—";
 }
 export function lastSeenLabel(lastSeenAt, format) {
@@ -72,33 +72,33 @@ export function lastSeenLabel(lastSeenAt, format) {
  */
 export function tokenFailureNotice(action, name, facts, productName) {
     if (facts.kind === "session")
-        return failure("Your session has ended. Sign in again, then retry.");
+        return failure("Session ended. Sign in again.");
     if (facts.kind === "forbidden")
-        return failure("You don't have permission to manage agent tokens.");
+        return failure("You can't manage agent tokens.");
     if (facts.kind === "stale") {
-        return failure(`${name}'s token changed before the request was sent, so nothing was sent. Check it and try again.`);
+        return failure(`${name}'s token changed, so nothing was sent. Try again.`);
     }
     if (facts.kind === "network") {
-        return failure(`Couldn't reach ${productName}. Refresh to check ${name}'s token before trying again.`);
+        return failure(`Couldn't reach ${productName}. Refresh to check ${name}'s token.`);
     }
     if (facts.status === 503) {
         return failure(action === "revoke"
-            ? `Revocation outcome unknown for ${name}: revoke again to be sure its token is stopped.`
-            : `${action === "issue" ? "Issue" : "Rotation"} outcome unknown for ${name}: no secret was returned, so rotate again for a replacement.`);
+            ? `Revoke result unknown for ${name}. Revoke again to be sure.`
+            : `${action === "issue" ? "Issue" : "Rotate"} result unknown for ${name}. No secret came back, so rotate again.`);
     }
     if (facts.status === 499) {
         return failure(action === "revoke"
-            ? `The request ended before ${name}'s revocation finished. Refresh to check its token before trying again.`
-            : `The request ended before ${name}'s token was delivered, so no secret was returned. Refresh to check its token before trying again.`);
+            ? `The request ended before ${name}'s revoke finished. Refresh to check its token.`
+            : `The request ended before ${name}'s token arrived. Refresh to check its token.`);
     }
     // The route's compare-and-swap refused it: the slot moved after the list was read.
     if (facts.status === 409 && facts.code === "slot_changed")
-        return failure("Changed since you looked, refresh.");
+        return failure("Changed since you looked. Refresh.");
     if (facts.status === 409)
-        return failure(`${name}'s token changed meanwhile. Reload and try again.`);
+        return failure(`${name}'s token changed. Reload and try again.`);
     if (facts.status === 404)
         return failure(`${name} is no longer declared in code. Reload the page.`);
     return action === "revoke"
-        ? failure(`${name}'s token could not be revoked. Reload and try again.`)
-        : failure(`A token could not be issued for ${name}. Reload and try again.`);
+        ? failure(`Couldn't revoke ${name}'s token. Reload and try again.`)
+        : failure(`Couldn't issue a token for ${name}. Reload and try again.`);
 }