@zackbart/connecta 0.40.0 → 0.41.0

package/dist/native-tools.js

@@ -1,3 +1,4 @@
+import { resolvedConnectorGuides } from "./skills.js";
 import { bytesToHex } from "./bytes.js";
 import { routeNames } from "./agent-routes.js";
 import { duringViewEffect } from "./runtime/call.js";
@@ -129,10 +130,12 @@ function passThroughSchema(schema) {
         },
     };
 }
-function describe(entry, executeCode) {
+function describe(entry, executeCode, guideName) {
     const lines = [entry.tool.description?.trim() || entry.tool.title || entry.tool.name];
     if (executeCode)
         lines.push(`Program address: ${entry.connector.id}.${entry.tool.name}`);
+    if (guideName)
+        lines.push(`Guide: skills ${guideName}`);
     return lines.join("\n\n");
 }
 export class NativeSurface {
@@ -177,10 +180,10 @@ export class NativeSurface {
     call(name, args, request) {
         return runEdge(authOwnMethod(NativeSurface.prototype, this, "call", [name, args, request]));
     }
-    registerTool(server, name, entry) {
+    registerTool(server, name, entry, guideName) {
         server.registerTool(name, {
             ...(entry?.tool.title ? { title: entry.tool.title } : {}),
-            ...(entry ? { description: describe(entry, this.options.executeCode) } : {}),
+            ...(entry ? { description: describe(entry, this.options.executeCode, guideName) } : {}),
             inputSchema: passThroughSchema(entry?.tool.inputSchema),
             ...(entry ? { annotations: annotationsFor(entry.tool) } : {}),
             ...(entry ? { _meta: { "dev.connecta/address": `${entry.connector.id}.${entry.tool.name}` } } : {}),
@@ -220,8 +223,12 @@ export class NativeSurface {
                     });
                     return;
                 }
+                const guides = yield* upwardStep(authCall(resolvedConnectorGuides, [
+                    self.registry.listConnectors(),
+                ]));
+                const guideNames = new Map(guides.map(({ connector, reference }) => [connector.id, reference]));
                 for (const entry of tools)
-                    self.registerTool(server, entry.name, entry);
+                    self.registerTool(server, entry.name, entry, guideNames.get(entry.connector.id));
             })).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
         }, NativeSurface.prototype.register);
         registerAuthMethod(NativeSurface.prototype, "call", function (name, args, request) {

package/dist/node.d.ts

@@ -8,6 +8,13 @@ export interface ListenOptions {
     host?: string;
     /** Pre-auth buffer cap, independent of the authenticated MCP cap. Default 4 MiB. */
     maxBodyBytes?: number;
+    /**
+     * Cap on the body bytes all in-flight requests hold together, counted as
+     * each arrives and released when its response finishes or its client leaves.
+     * Past it a request is answered 503 with `Retry-After`. Default 64 MiB, or
+     * `maxBodyBytes` when larger. May not be below `maxBodyBytes`.
+     */
+    maxInFlightBodyBytes?: number;
     /**
      * Stop accepting connections on SIGTERM/SIGINT, let in-flight requests
      * finish, drain deferred work, then exit. Default true — Docker sends

package/dist/node.js

@@ -5,13 +5,40 @@ import { failureRecord, logFailure } from "./operator-record.js";
 import { configureGuardedTransport } from "./guarded-transport.js";
 import { createNodeGuardedTransport } from "./http/node-transport.js";
 import { CONFIG_DEFAULTS } from "./config-defaults.js";
+import { ConfigError } from "./config-schema.js";
 /** The adapter buffers before auth, bounded by the same default as the core. */
 const DEFAULT_MAX_BODY_BYTES = CONFIG_DEFAULTS.admission.requests.maxBodyBytes;
+/** Sixteen full default bodies; well above ordinary MCP traffic, whose bodies are small. */
+const DEFAULT_MAX_IN_FLIGHT_BODY_BYTES = 64 * 1024 * 1024;
 const BODY_TOO_LARGE = Symbol("body-too-large");
-async function toRequest(req, maxBodyBytes, signal) {
+const BODIES_AT_CAPACITY = Symbol("bodies-at-capacity");
+/** A name, IPv4 or bracketed IPv6 host with an optional port, and nothing else. */
+const REQUEST_HOST = /^(?:[a-z0-9._-]+|\[[0-9a-f:.]+\])(?::\d{1,5})?$/i;
+/** `Host`, `X-Forwarded-Proto` or the request target is not a URL part; answered 400. */
+class InvalidRequestUrl extends Error {
+}
+/**
+ * The request's URL, read from values a client chooses. Each is checked on its
+ * own and the origin is parsed before the target joins it, so no value can move
+ * the boundary between authority, path and query for the routes behind it.
+ */
+function requestUrl(req) {
     const host = req.headers.host ?? "localhost";
     const proto = req.headers["x-forwarded-proto"] ?? "http";
-    const url = `${proto}://${host}${req.url ?? "/"}`;
+    // Origin-form only. Absolute-form and `*` have no path to route.
+    const target = req.url ?? "/";
+    if (!REQUEST_HOST.test(host) || typeof proto !== "string" || !/^https?$/i.test(proto) || !target.startsWith("/")) {
+        throw new InvalidRequestUrl();
+    }
+    try {
+        return `${new URL(`${proto}://${host}`).origin}${target}`;
+    }
+    catch {
+        throw new InvalidRequestUrl();
+    }
+}
+async function toRequest(req, maxBodyBytes, holdBodyBytes, signal) {
+    const url = requestUrl(req);
     const method = req.method ?? "GET";
     const headers = new Headers();
     for (const [key, value] of Object.entries(req.headers)) {
@@ -29,6 +56,8 @@ async function toRequest(req, maxBodyBytes, signal) {
             // rest of a body we have already decided to reject.
             if (size > maxBodyBytes)
                 return BODY_TOO_LARGE;
+            if (!holdBodyBytes(chunk.length))
+                return BODIES_AT_CAPACITY;
             chunks.push(chunk);
         }
         if (chunks.length)
@@ -64,6 +93,13 @@ export function listen(connecta, portOrOptions) {
     const opts = typeof portOrOptions === "number" ? { port: portOrOptions } : portOrOptions;
     configureGuardedTransport(createNodeGuardedTransport(opts.proxy));
     const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const maxInFlightBodyBytes = opts.maxInFlightBodyBytes === undefined
+        ? Math.max(DEFAULT_MAX_IN_FLIGHT_BODY_BYTES, maxBodyBytes)
+        : opts.maxInFlightBodyBytes;
+    if (!Number.isSafeInteger(maxInFlightBodyBytes) || maxInFlightBodyBytes < 1 || maxInFlightBodyBytes < maxBodyBytes) {
+        throw new ConfigError("listen: maxInFlightBodyBytes must be a whole number of bytes, at least maxBodyBytes.");
+    }
+    let inFlightBodyBytes = 0;
     // Node has no ExecutionContext, so deferred work (activity sinks) would
     // otherwise be an untracked floating promise. Track it here and drain it on
     // shutdown so both runtimes behave the same.
@@ -101,7 +137,19 @@ export function listen(connecta, portOrOptions) {
         res.once("close", finished);
         void (async () => {
             const controller = new AbortController();
+            let heldBodyBytes = 0;
+            let bodyBytesReleased = false;
+            // Pipeline teardown can wait forever on a response stream's cancel().
+            // Release on the HTTP lifecycle too, and forbid late upload reservations.
+            const releaseBodyBytes = () => {
+                if (bodyBytesReleased)
+                    return;
+                bodyBytesReleased = true;
+                inFlightBodyBytes -= heldBodyBytes;
+                heldBodyBytes = 0;
+            };
             const abortRequest = () => {
+                releaseBodyBytes();
                 if (!controller.signal.aborted) {
                     controller.abort(new Error("HTTP client disconnected."));
                 }
@@ -117,8 +165,28 @@ export function listen(connecta, portOrOptions) {
             req.once("aborted", abortRequest);
             req.once("close", abortIncompleteRequest);
             res.once("close", abortIncompleteResponse);
+            res.once("finish", releaseBodyBytes);
+            res.once("close", releaseBodyBytes);
+            // A queued pipelined response gets neither finish nor close when the
+            // socket goes away, and its completed upload's request is already closed.
+            socket.once("close", abortRequest);
+            const holdBodyBytes = (bytes) => {
+                if (bodyBytesReleased || inFlightBodyBytes + bytes > maxInFlightBodyBytes)
+                    return false;
+                inFlightBodyBytes += bytes;
+                heldBodyBytes += bytes;
+                return true;
+            };
             try {
-                const request = await toRequest(req, maxBodyBytes, controller.signal);
+                const request = await toRequest(req, maxBodyBytes, holdBodyBytes, controller.signal);
+                if (request === BODIES_AT_CAPACITY) {
+                    res.statusCode = 503;
+                    res.setHeader("Retry-After", "1");
+                    // Abandoned mid-body, like the 413 below.
+                    res.setHeader("Connection", "close");
+                    res.end("Service Unavailable");
+                    return;
+                }
                 if (request === BODY_TOO_LARGE) {
                     res.statusCode = 413;
                     // The request stream was abandoned mid-body, so this connection
@@ -132,6 +200,13 @@ export function listen(connecta, portOrOptions) {
                 await writeResponse(res, response);
             }
             catch (error) {
+                if (error instanceof InvalidRequestUrl) {
+                    res.statusCode = 400;
+                    // Refused before reading the body, so the connection cannot be reused.
+                    res.setHeader("Connection", "close");
+                    res.end("Bad Request");
+                    return;
+                }
                 // A client that deliberately went away can make either the request
                 // handler or response pipeline reject. The request's abort signal is
                 // the authoritative classification: there is no caller left to answer,
@@ -152,6 +227,10 @@ export function listen(connecta, portOrOptions) {
                 res.end("Internal Server Error");
             }
             finally {
+                releaseBodyBytes();
+                res.removeListener("finish", releaseBodyBytes);
+                res.removeListener("close", releaseBodyBytes);
+                socket.removeListener("close", abortRequest);
                 req.removeListener("aborted", abortRequest);
                 req.removeListener("close", abortIncompleteRequest);
                 res.removeListener("close", abortIncompleteResponse);

package/dist/operation-activity.js

@@ -0,0 +1,103 @@
+// The root graph calls the optional recorder, never the /activity implementation.
+import { Cause, Effect, Exit } from "effect";
+import { InvocationFailure } from "./invocation-failure.js";
+import { ExecutorAdmissionError } from "./executor-admission.js";
+import { DiscoveryPolicyError } from "./catalog-service.js";
+import { classificationCode, classifyCallError } from "./errors.js";
+import { usesCallerIdentity } from "./connector-caller.js";
+export function operationActivity(context, registry, name, work, counts) {
+    if (!context?.recordOperation)
+        return work;
+    return Effect.suspend(() => {
+        const started = performance.now();
+        const connectors = registry.listConnectors();
+        // Human operations stay owner-only, including discovery of private catalogs.
+        let personal = Boolean(context.principalActor);
+        try {
+            personal ||= connectors.some((connector) => connector.authScope === "personal" ||
+                !connector.staticTools ||
+                usesCallerIdentity(connector) ||
+                connector.describe?.().auth?.mode === "request");
+        }
+        catch {
+            personal = true;
+        }
+        return work.pipe(Effect.onExit((exit) => Effect.sync(() => {
+            const result = Exit.isSuccess(exit)
+                ? exit.value
+                : undefined;
+            const failed = Exit.isFailure(exit) || result?.isError === true;
+            const interrupted = Exit.isFailure(exit) && exit.cause.reasons.some(Cause.isInterruptReason);
+            const failure = Exit.isFailure(exit) ? Cause.squash(exit.cause) : undefined;
+            const errorCode = interrupted
+                ? "cancelled"
+                : classificationCode(Exit.isFailure(exit)
+                    ? failure instanceof InvocationFailure ||
+                        failure instanceof ExecutorAdmissionError ||
+                        failure instanceof DiscoveryPolicyError
+                        ? failure.code
+                        : classifyCallError(failure).code
+                    : result?.structuredContent?.error?.code);
+            try {
+                // Result pages already measure their payload. Other operations have no
+                // reusable measurement: never serialize discovery or media for telemetry.
+                const page = name === "result" && Exit.isSuccess(exit)
+                    ? exit.value
+                    : undefined;
+                const bytes = page?.structuredContent?.bytes ?? page?.bytes;
+                const resultBytes = typeof bytes === "number" && Number.isSafeInteger(bytes) && bytes >= 0 ? bytes : undefined;
+                context.recordOperation(context, {
+                    operation: {
+                        name,
+                        connectors: connectors.map((connector) => connector.id),
+                        personal,
+                        ...(counts ? { hostCalls: counts() } : {}),
+                    },
+                    durationMs: performance.now() - started,
+                    resultBytes,
+                    outcome: !failed
+                        ? "success"
+                        : errorCode === "timeout"
+                            ? "timeout"
+                            : errorCode === "cancelled" || errorCode === "executor_cancelled"
+                                ? "cancelled"
+                                : "error",
+                    errorCode,
+                });
+            }
+            catch {
+                /* Optional recording cannot replace the operation's result. */
+            }
+        })));
+    });
+}
+const OPERATION_NAMES = new Set(["search", "describe", "result", "skill", "program"]);
+export function checkedActivityOperation(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const input = value;
+    if (!OPERATION_NAMES.has(input.name) ||
+        typeof input.personal !== "boolean" ||
+        !Array.isArray(input.connectors) ||
+        input.connectors.some((id) => typeof id !== "string" || !/^[a-zA-Z0-9_-]+$/.test(id)))
+        return undefined;
+    const counts = input.hostCalls;
+    if (counts &&
+        [counts.attempted, counts.admitted, counts.succeeded, counts.failed].some((n) => typeof n !== "number" || !Number.isSafeInteger(n) || n < 0))
+        return undefined;
+    return {
+        name: input.name,
+        connectors: [...new Set(input.connectors)],
+        personal: input.personal,
+        ...(counts
+            ? {
+                hostCalls: {
+                    attempted: counts.attempted,
+                    admitted: counts.admitted,
+                    succeeded: counts.succeeded,
+                    failed: counts.failed,
+                },
+            }
+            : {}),
+    };
+}

package/dist/operator-record.d.ts

@@ -23,8 +23,15 @@ export declare function labelErrorClass(ctor: {
  * name is exactly one of those, else `DOMException`.
  */
 export declare function errorLabel(failure: unknown): string | undefined;
+interface IdentityLookupFact {
+    outcome: "timeout" | "rejected";
+    durationMs: number;
+    cold: boolean;
+    inFlight: number;
+}
 /** Facts connecta derived about a failure where it saw it. */
 export interface FailureFacts {
+    identityLookup?: IdentityLookupFact;
     /** Inbound refusal classification attached to its Response, never its body. */
     reason?: AuthDenialReason;
     step?: FailureStep;
@@ -64,6 +71,7 @@ export interface FailureSubject {
 declare const recordBrand: unique symbol;
 /** One failure as an operator may read it. Only `failureRecord` makes one. */
 export interface FailureRecord {
+    readonly identityLookup?: IdentityLookupFact;
     readonly [recordBrand]: true;
     readonly reason?: AuthDenialReason;
     readonly accessContext?: boolean;

package/dist/operator-record.js

@@ -165,6 +165,20 @@ export function errorLabel(failure) {
     }
     return undefined;
 }
+function identityLookupFact(value) {
+    if (!value ||
+        (value.outcome !== "timeout" && value.outcome !== "rejected") ||
+        count(value.durationMs, 86_400_000) === undefined ||
+        typeof value.cold !== "boolean" ||
+        count(value.inFlight, 1_000) === undefined)
+        return undefined;
+    return {
+        outcome: value.outcome,
+        durationMs: Math.round(value.durationMs),
+        cold: value.cold,
+        inFlight: Math.round(value.inFlight),
+    };
+}
 function origin(value) {
     if (typeof value !== "string")
         return undefined;
@@ -190,6 +204,7 @@ function checkedFacts(facts) {
     return {
         ...defined("reason", member(facts.reason, AUTH_DENIAL_REASONS)),
         ...defined("step", member(facts.step, STEPS)),
+        ...defined("identityLookup", identityLookupFact(facts.identityLookup)),
         ...defined("origin", origin(facts.origin)),
         ...defined("httpStatus", httpStatus(facts.httpStatus)),
         ...defined("oauthError", member(facts.oauthError, OAUTH_ERROR_CODES)),