@zackbart/connecta 0.18.1 → 0.18.3

package/CHANGELOG.md

@@ -2,6 +2,86 @@
 
 All notable changes to this package are documented here.
 
+## 0.18.3 — 2026-08-25
+
+This change gives code mode memory where downstream MCP catalogs are usually
+silent: after a successful call with no declared output schema, Connecta keeps
+only the result's field names and broad JSON types and shows that open shape on
+later discovery. Nothing breaks, no deployment option changes, and providers
+that already declare outputs are untouched. The bounded cache lives only in the
+current process or Worker isolate and forgets each shape after 24 hours.
+Discovery still never executes a tool, and
+the new `outputSchemaSource: "observed"` marker is the warning label that keeps
+one or several real results from masquerading as a provider contract.
+
+### Added
+
+- **Passive observed output schemas.** Successful explicitly read-only calls
+  whose provider declared no `outputSchema` infer and merge an open
+  optional-field schema of names and broad JSON types. The inference retains no
+  arguments, scalar values, raw results, code, credentials, or errors. Property
+  names may be user-authored. It bounds depth, breadth, names, nodes, definition
+  size, and schema bytes; keeps at most 256 runtime entries; ties each entry to
+  the exact tool definition; and expires it after 24 hours.
+  Search and describe return it with `outputSchemaSource: "observed"`; a
+  declared schema always wins. Observation is synchronous, storage-free, and
+  unable to fail the call. The design follows new warm-cache evidence and two
+  live deployment audits: BePresent had 246/378 tools without output schemas,
+  while OneMany's maintained connectors declared all 90 (#442).
+
+## 0.18.2 — 2026-08-18
+
+This patch closes the gap the RevenueCat rollout exposed on the same day 0.18.1
+shipped: a hosted-MCP connection could authenticate with OAuth from the
+Connections page or with a header literal baked into the deployment file, but
+never with a key an operator pastes on `/credentials` the way every `api()`
+connector already can. Now it can. Nothing breaks, no constructor changes, and a
+deployment that keeps its static keys in runtime secrets can ignore this release.
+Two things are worth reading before adopting the new shape: the operator vault
+(`credentials.encryptionKey`) must be configured, and a key pasted with a
+wrapped newline is refused before it is framed rather than echoed back by the
+runtime that rejects it.
+
+### Added
+
+- **`auth: { type: "credential" }` for `remoteMcp()` and every maintained
+  hosted connection.** The connector declares an operator credential slot on
+  `/credentials` (label and guidance from the provider, overridable), reads the
+  stored value on every request before trusting a cached client, and frames it
+  as `Authorization: Bearer <value>` by default — `header` and `scheme` are
+  configurable, `scheme: null` sends the value bare, and a scheme ending in
+  `Basic` base64-encodes it, which is how Mixpanel's documented
+  `Bearer Basic <base64(user:secret)>` is spelled. A missing or empty value is
+  `auth_required`, and `authorize_connector` returns the operator handoff to
+  `/credentials`; a deployment without a vault warns at construction and answers
+  `recovery: "unavailable"` at use. Rotation on `/credentials` takes effect on
+  the next call: a SHA-256 digest of the connected value is compared per
+  request (including against an in-flight connect) and a differing digest
+  closes the old client. The `/credentials` Test action connects with the
+  candidate and counts the catalog, and only when an operator presses it — the
+  #179 refusal of proactive probing stands, now written into P10. Provider
+  defaults: Stripe (requires `mode`, refuses `connectedAccount`), Linear
+  (Bearer, per Linear's MCP docs), Mixpanel (`Bearer Basic`, service account),
+  RevenueCat (single-project branch, "API v2 secret key") (#439).
+
+### Changed
+
+- **A stored credential never reaches an agent or operator surface, even
+  malformed.** The value is refused before framing if it carries a control
+  character (the wrapped-newline paste), with a message that names the problem
+  and not the value; behind that, any error whose message or `cause` chain
+  quotes the raw or framed value is replaced whole rather than redacted. Both
+  layers are tested independently (#439).
+
+- **Provider conventions P9 and P10 say what is now true.** P9 names both
+  headless shapes and requires the framing to match the provider's published
+  MCP contract; P10 is retitled to allow an operator-requested credential test
+  while forbidding any unasked probe (#439).
+
+- **Linear's headers example uses `Bearer`.** Linear's MCP server documents
+  `Authorization: Bearer <token>` for API keys; the bare form is its GraphQL
+  convention. Existing `headers` connectors are untouched (#439).
+
 ## 0.18.1 — 2026-08-18
 
 This patch is the response to one long investigation run against a live

package/README.md

@@ -67,6 +67,10 @@ Fifty issues in, one small object out. Your context window notices.
   classifications, imported one at a time.
 - **Let the agent work in code.** Search, chain, filter, join, and reduce
   inside the sandbox instead of round-tripping every call through the model.
+- **Teach undeclared result shapes by using them.** Successful read-only calls
+  retain field names and broad types in bounded runtime memory, never scalar
+  values, so later programs can project a remote MCP result its provider never
+  documented.
 - **Keep writes deliberate.** Only tools marked read-only run in a program.
   Everything else is a separate, visible call your client can gate.
 - **Run it where you like.** Node, a Docker container, or a Cloudflare Worker,

package/dist/catalog-service.d.ts

@@ -49,6 +49,7 @@ interface CatalogSearchEntry {
         description?: string;
         inputSchema?: unknown;
         outputSchema?: unknown;
+        outputSchemaSource?: "observed";
         inputSchemaTruncated?: true;
         outputSchemaTruncated?: true;
         inputKeys?: string[];
@@ -112,6 +113,7 @@ export interface CatalogDescription {
     guideRequiredReasons?: GuideRequiredReason[];
     inputSchema?: unknown;
     outputSchema?: unknown;
+    outputSchemaSource?: "observed";
     annotations?: ToolDef["annotations"];
     error?: string;
     errorDetails?: CatalogDescriptionFailureDetail;
@@ -174,6 +176,7 @@ export declare class CatalogService {
     }, purpose: string): NonNullable<CallErrorDetails["nextAction"]>;
     loadConnector(id: string, callOptions?: ConnectorOperationOptions): Promise<ToolDef[]>;
     private loadForDiscovery;
+    private outputSchema;
     resolveTool(address: string, callOptions?: ConnectorOperationOptions): Promise<CatalogResolution>;
     /**
      * Resolve the JavaScript-safe property used by a lazy code-mode namespace
@@ -242,6 +245,7 @@ export declare function flatSearchResult(page: CatalogSearchPage): {
         description?: string;
         inputSchema?: unknown;
         outputSchema?: unknown;
+        outputSchemaSource?: "observed";
         inputSchemaTruncated?: true;
         outputSchemaTruncated?: true;
         inputKeys?: string[];

package/dist/catalog-service.js

@@ -266,6 +266,14 @@ export class CatalogService {
             timeoutMs: this.probeTimeoutMs,
         }), this.probeTimeoutMs, label);
     }
+    outputSchema(connectorId, tool) {
+        if (tool.outputSchema)
+            return { schema: tool.outputSchema };
+        const observed = this.registry.observedOutputSchema(connectorId, tool);
+        return observed
+            ? { schema: observed, source: "observed" }
+            : {};
+    }
     async resolveTool(address, callOptions = {}) {
         const resolved = this.registry.resolveAddress(address);
         if (!resolved) {
@@ -487,15 +495,18 @@ export class CatalogService {
         });
         const pageMatches = matches.slice(offset, offset + limit);
         const entries = pageMatches.map((match) => {
+            const output = args.includeSchemas
+                ? this.outputSchema(match.connector.id, match.tool)
+                : {};
             const input = match.tool.inputSchema ?? { type: "object" };
             const renderedInput = args.includeSchemas
                 ? renderSearchSchema(input, args.includeSchemas)
                 : undefined;
-            const renderedOutput = args.includeSchemas && match.tool.outputSchema
-                ? renderSearchSchema(match.tool.outputSchema, args.includeSchemas)
+            const renderedOutput = args.includeSchemas && output.schema
+                ? renderSearchSchema(output.schema, args.includeSchemas)
                 : undefined;
             const schemaKeys = args.includeSchemas && args.includeSchemaKeys
-                ? schemaKeyMetadata(input, match.tool.outputSchema)
+                ? schemaKeyMetadata(input, output.schema)
                 : undefined;
             const description = summarizeDiscoveryDescription(match.tool.description, args.fullDescriptions === true);
             const requiredReasons = guideRequiredReasons(match.connector, match.tool, renderedInput?.truncated === true || renderedOutput?.truncated === true);
@@ -520,11 +531,14 @@ export class CatalogService {
                     ...(renderedInput?.truncated
                         ? { inputSchemaTruncated: true }
                         : {}),
-                    ...(args.includeSchemas && match.tool.outputSchema
+                    ...(args.includeSchemas && output.schema
                         ? {
                             outputSchema: renderedOutput?.schema,
                         }
                         : {}),
+                    ...(args.includeSchemas && output.source
+                        ? { outputSchemaSource: output.source }
+                        : {}),
                     ...(renderedOutput?.truncated
                         ? { outputSchemaTruncated: true }
                         : {}),
@@ -813,6 +827,7 @@ 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 guideSummary = connectorGuideSummary(addressResolution.connector);
@@ -833,11 +848,12 @@ export class CatalogService {
                     }
                     : {}),
                 inputSchema: renderSchema(input, format),
-                ...(tool.outputSchema
+                ...(output.schema
                     ? {
-                        outputSchema: renderSchema(tool.outputSchema, format),
+                        outputSchema: renderSchema(output.schema, format),
                     }
                     : {}),
+                ...(output.source ? { outputSchemaSource: output.source } : {}),
                 ...(tool.annotations ? { annotations: tool.annotations } : {}),
             };
         });

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

@@ -1,12 +1,58 @@
 import type { FetchLike, Transport } from "@modelcontextprotocol/client";
 import { ConnectorCallError } from "../errors.js";
-import type { Connector, ConnectorCallAdmissionPolicy, ConnectorContext, ConnectorUsageGuide, Logger } from "../types.js";
+import type { Connector, ConnectorCallAdmissionPolicy, ConnectorContext, ConnectorCredentialConfig, ConnectorUsageGuide, Logger } from "../types.js";
+/**
+ * A static downstream credential the operator supplies at `/credentials`
+ * rather than the deployment baking into its source.
+ *
+ * The connector, its endpoint, and the credential *slot* stay declared in
+ * code; only the secret arrives through the operator route, exactly as for
+ * `api()`. One reserved `value` field, deliberately: a header is assembled
+ * from a name, a framing scheme, and one secret, and anything that needs two
+ * secrets composed into one header is a provider integration, not a proxy
+ * config ([#439](https://github.com/zackbart/connecta/issues/439)).
+ */
+interface RemoteMcpCredentialAuth {
+    type: "credential";
+    /**
+     * Operator-facing slot description rendered on `/credentials`. Defaults to
+     * `{ label: "API key" }`; a maintained provider passes the name the provider
+     * itself uses. Named `fields` are refused — this shape reads the reserved
+     * `value` field only.
+     */
+    credential?: ConnectorCredentialConfig;
+    /** Header the credential rides. Defaults to `Authorization`. */
+    header?: string;
+    /**
+     * Framing token placed before the value. Defaults to `"Bearer"`. `null` (or
+     * an empty string) sends the stored value verbatim, for an endpoint that
+     * reads a bare key. A scheme whose last token is `Basic` declares
+     * HTTP Basic credentials: the stored `user:secret` is base64-encoded first,
+     * so `"Basic"` produces `Basic <base64>` and Mixpanel's documented
+     * `"Bearer Basic"` produces `Bearer Basic <base64>`.
+     */
+    scheme?: string | null;
+}
 export type RemoteMcpAuth = {
     type: "headers";
     headers: Record<string, string>;
-} | {
+} | RemoteMcpCredentialAuth | {
     type: "oauth";
 };
+/**
+ * Apply a maintained provider's slot copy and header framing to credential
+ * auth the deployment left bare.
+ *
+ * A provider knows what its own key is called and how the endpoint expects it
+ * framed; a deployment that states either one keeps its answer. Every other
+ * auth shape passes through untouched, so a provider can hand this its whole
+ * `auth` option without branching first.
+ */
+export declare function withCredentialDefaults(auth: RemoteMcpAuth, defaults: {
+    credential: ConnectorCredentialConfig;
+    /** Provider framing; omit to leave the `Bearer` default in place. */
+    scheme?: string | null;
+}): RemoteMcpAuth;
 export type RemoteMcpRedirectPolicy = "none" | "same-origin";
 export interface RemoteMcpOptions {
     url: string;
@@ -90,3 +136,4 @@ export declare function redirectSafeFetch(connectorId: string, policy?: RemoteMc
  * server or hide other connectors).
  */
 export declare function remoteMcp(id: string, opts: RemoteMcpOptions): Connector;
+export {};