@zackbart/connecta 0.39.0 → 0.41.0

package/dist/meta-tools.js

@@ -1,3 +1,6 @@
+import { operationActivity } from "./operation-activity.js";
+import { SkillLookupError } from "./skills.js";
+import { skillLookupRecovery, utilityRecovery } from "./utility-recovery.js";
 import { META_ROUTES } from "./agent-routes.js";
 import { toolError } from "./tool-error.js";
 import { upwardStep } from "./upward.js";
@@ -38,6 +41,9 @@ export function jsonResult(obj, text = JSON.stringify(obj)) {
 function errorResult(message) {
     return { content: [{ type: "text", text: message }], isError: true };
 }
+function resultError(message) {
+    return toolError(utilityRecovery("invalid_args", message));
+}
 function discoveryErrorResult(error) {
     return toolError({ code: error.code, message: error.message, retryable: false });
 }
@@ -558,6 +564,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
     }
     const sentSecrets = sentSecretsForRequest(requestScope);
     const skills = new SkillsRegistry(registry, baseUrl, {
+        readOnly: opts.readOnly,
         requestScope,
         requestSignal: opts.requestSignal,
         probeTimeoutMs,
@@ -731,7 +738,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             };
         });
     });
-    return {
+    const methods = {
         skills: authMethod((args = {}) => authFlow(function* () {
             try {
                 if (!args.name) {
@@ -751,7 +758,9 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                 return { content: [{ type: "text", text }], structuredContent: { name: args.name, format: "text", text } };
             }
             catch (error) {
-                return errorResult(error instanceof ConnectorCallError ? error.message : "Skills are unavailable.");
+                if (error instanceof SkillLookupError)
+                    return toolError(skillLookupRecovery(error.message));
+                return toolError(utilityRecovery(error instanceof ConnectorCallError ? error.code : "unavailable", "Skills are unavailable.", error instanceof ConnectorCallError && error.retryable));
             }
         })),
         searchTools: authMethod((args) => authFlow(function* () {
@@ -781,25 +790,21 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             // Defense for in-process callers too: guest paging validates these domains
             // before calling here, while internal consumers may call readResult directly.
             if (args.maxBytes !== undefined && !isValidMaxResultBytes(args.maxBytes)) {
-                return errorResult(`Invalid maxBytes ${args.maxBytes}: must be a whole number of bytes ` +
+                return resultError(`Invalid maxBytes ${args.maxBytes}: must be a whole number of bytes ` +
                     `>= ${MIN_MAX_RESULT_BYTES}. Omit it to use the deployment default.`);
             }
             if (args.offset !== undefined && !isValidResultOffset(args.offset)) {
-                return errorResult(`Invalid offset ${args.offset}: must be a whole number of bytes ` +
+                return resultError(`Invalid offset ${args.offset}: must be a whole number of bytes ` +
                     `>= ${MIN_RESULT_OFFSET}. Omit it to start at the beginning.`);
             }
             if (args.page !== undefined &&
                 (!Number.isSafeInteger(args.page) || args.page < 0 || args.offset !== undefined)) {
-                return errorResult("Use a whole page >= 0, without offset.");
+                return resultError("Use a whole page >= 0, without offset.");
             }
             const results = registry.resultsStorage();
             const unavailableResult = () => ({
                 ...jsonResult({
-                    error: {
-                        code: "unavailable",
-                        message: "Result paging storage is unavailable.",
-                        retryable: true,
-                    },
+                    error: utilityRecovery("unavailable", "Result paging storage is unavailable.", true),
                 }),
                 isError: true,
             });
@@ -825,9 +830,9 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             if (stored === false)
                 return unavailableResult();
             if (stored === null) {
-                return errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
+                return toolError(utilityRecovery("not_found", `Unknown or expired result id "${boundedEchoText(args.id, 96)}"`));
             }
-            const denied = () => errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
+            const denied = () => toolError(utilityRecovery("not_found", `Unknown or expired result id "${boundedEchoText(args.id, 96)}"`));
             const header = RESULT_ENVELOPE_V4_HEADER.exec(stored);
             if (!header)
                 return denied();
@@ -941,7 +946,7 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
                     if (encoded === null) {
                         // A chunk expired or was evicted under its own header; the id can no
                         // longer serve this range, and inventing U+0000 filler would be worse.
-                        return errorResult(`Unknown or expired result id "${boundedEchoText(args.id)}"`);
+                        return toolError(utilityRecovery("not_found", `Unknown or expired result id "${boundedEchoText(args.id, 96)}"`));
                     }
                     const chunkStart = index * chunkBytes;
                     // Both bounds are chunk-local. `from` inherits `start`'s three-byte
@@ -999,6 +1004,15 @@ function metaToolsForRequest(registry, baseUrl, opts = {}) {
             }
         })),
     };
+    if (!opts.activity?.recordOperation)
+        return methods;
+    const track = (name, method) => authMethod((...args) => operationActivity(opts.activity, registry, name, authCall(method, args)));
+    return {
+        ...methods,
+        skills: track("skill", methods.skills),
+        searchTools: track("search", methods.searchTools),
+        readResult: track("result", methods.readResult),
+    };
 }
 // Each description states only its own tool's scope; the full routing rule
 // lives once in the server instructions. A client that drops instructions
@@ -1130,6 +1144,37 @@ export function registerMetaTools(server, registry, ctx) {
         bindRequest(request);
         return yield* upwardStep(authInvoke(mt, "skills", [args]));
     })));
+    server.registerTool("authorize_connector", {
+        description: ctx.native
+            ? AUTHORIZE_DESC +
+                " Use when a connector’s tools are missing. Granted: " +
+                registry
+                    .listConnectors()
+                    .map((connector) => connector.id)
+                    .join(", ") +
+                "."
+            : AUTHORIZE_DESC,
+        inputSchema: AUTHORIZE_INPUT,
+        outputSchema: AUTHORIZE_OUTPUT,
+        // Starts (or with force, resets) a downstream OAuth flow — it changes
+        // stored connector auth state, so it is deliberately not read-only.
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    }, authMethod((args, request) => authFlow(function* () {
+        bindRequest(request);
+        const run = authMethod(() => authInvoke(mt, "authorizeConnector", [args]));
+        return yield* upwardStep(ctx.authElicitation
+            ? authInvoke(ctx.authElicitation, "run", [
+                "authorize_connector",
+                args,
+                request,
+                run,
+            ])
+            : authCall(run, []));
+    })));
     if (ctx.native) {
         if (!ctx.native.executeCode) {
             server.registerTool("read_result", { description: READ_RESULT_DESC, inputSchema: READ_RESULT_INPUT, annotations: READ_ONLY_LOCAL }, authMethod((args, request) => authFlow(function* () {
@@ -1201,28 +1246,5 @@ export function registerMetaTools(server, registry, ctx) {
             ])
             : authInvoke(mt, "callDestructiveTool", [call]));
     })));
-    server.registerTool("authorize_connector", {
-        description: AUTHORIZE_DESC,
-        inputSchema: AUTHORIZE_INPUT,
-        outputSchema: AUTHORIZE_OUTPUT,
-        // Starts (or with force, resets) a downstream OAuth flow — it changes
-        // stored connector auth state, so it is deliberately not read-only.
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            openWorldHint: true,
-        },
-    }, authMethod((args, request) => authFlow(function* () {
-        bindRequest(request);
-        const run = authMethod(() => authInvoke(mt, "authorizeConnector", [args]));
-        return yield* upwardStep(ctx.authElicitation
-            ? authInvoke(ctx.authElicitation, "run", [
-                "authorize_connector",
-                args,
-                request,
-                run,
-            ])
-            : authCall(run, []));
-    })));
     return undefined;
 }

package/dist/module-contracts.d.ts

@@ -1,5 +1,5 @@
 import type { ConnectaBranding } from "./types.js";
-import type { ActivityStore, ActivityReadGate, recordToolActivity, recordCatalogChangeActivity } from "./activity.js";
+import type { ActivityStore, ActivityReadGate, recordToolActivity, recordCatalogChangeActivity, recordOperationActivity } from "./activity.js";
 import type { RouteContext } from "./routes/shared.js";
 /** Construction-time UI contract. Core never imports the implementation. */
 export interface OperatorSurface {
@@ -10,6 +10,8 @@ export interface OperatorSurface {
 }
 /** Optional recording and reading callbacks supplied by /activity. */
 export interface ActivityModule {
+    readonly operations?: boolean;
+    readonly recordOperation?: typeof recordOperationActivity;
     readonly store: ActivityStore;
     readonly deploymentId?: string;
     readonly readGate?: ActivityReadGate;

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";
@@ -29,7 +30,7 @@ const SEPARATOR = "__";
 const PLAIN_TOOL = /^[A-Za-z0-9-](?:[A-Za-z0-9-]|_(?!_))*$/;
 const NATIVE_NAME = new RegExp(`^[A-Za-z][A-Za-z0-9_-]{0,${NATIVE_NAME_MAX - 1}}$`);
 /** Connecta's own tools on a native endpoint. Their names never contain `__`. */
-const NATIVE_OWN_TOOLS = ["execute_code", "skills", "read_result"];
+const NATIVE_OWN_TOOLS = ["execute_code", "skills", "read_result", "authorize_connector"];
 const enc = new TextEncoder();
 function shortHash(text) {
     return runEdge(shortHashNative(text));
@@ -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)),