@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/schema.js

@@ -41,6 +41,8 @@ export function safeParseSchemaSync(schema, value, fieldPath) {
 export const APIFUSE_SENSITIVE_META_KEY = "x-apifuse-sensitive";
 export const APIFUSE_SENSITIVE_KIND_META_KEY = "x-apifuse-sensitive-kind";
 export const APIFUSE_DESCRIPTION_KEY_META_KEY = "x-apifuse-description-key";
+export const APIFUSE_CONTENT_TRUST_META_KEY = "x-apifuse-content-trust";
+export const APIFUSE_CONTENT_PROVENANCE_META_KEY = "x-apifuse-content-provenance";
 export const APIFUSE_REDACTION_MARKER = "<redacted>";
 export function describeKey(schema, key) {
     const descriptionKey = providerLocaleKey(key);
@@ -50,6 +52,20 @@ export function describeKey(schema, key) {
         [APIFUSE_DESCRIPTION_KEY_META_KEY]: descriptionKey,
     });
 }
+/**
+ * Mark an output field as externally authored text (listing bodies, reviews,
+ * posts) that the provider relays verbatim. Sets both content-trust JSON Schema
+ * meta keys on the field node so the platform can enforce the boundary when it
+ * assembles tool output; validation and the parsed value are unchanged.
+ */
+export function untrustedContent(schema) {
+    const metadata = schema.meta() ?? {};
+    return schema.meta({
+        ...metadata,
+        [APIFUSE_CONTENT_TRUST_META_KEY]: "untrusted",
+        [APIFUSE_CONTENT_PROVENANCE_META_KEY]: "external",
+    });
+}
 const describeKeyMethod = function (key) {
     return describeKey(this, key);
 };
@@ -97,15 +113,41 @@ export function field(schema, options = {}) {
         ? schema.describe(options.description)
         : schema;
     const metadata = described.meta() ?? {};
+    const isSensitive = options.sensitive ?? true;
+    // A public declaration only rewrites the meta of the node it receives;
+    // z.toJSONSchema folds that over the inner leaf, so `false` on a wrapper
+    // around a sensitive() leaf would publish `false` next to the leaf's kind
+    // while collectSensitivePaths() still redacts. Refuse the contradiction.
+    if (!isSensitive && wrapsSensitiveDeclaration(described)) {
+        throw new TypeError("publicField()/field({ sensitive: false }) wraps a sensitive() declaration; apply it to the leaf, before .optional(), .nullable(), .default(), .pipe(), z.lazy() or similar wrappers.");
+    }
+    // Zod merges meta with the parent chain, so an inherited kind can only be
+    // cleared by writing undefined over it (dropped from JSON Schema output).
+    const kind = isSensitive
+        ? (options.kind ?? Reflect.get(metadata, APIFUSE_SENSITIVE_KIND_META_KEY))
+        : undefined;
     return described.meta({
         ...metadata,
-        ...((options.sensitive ?? true) ? { [APIFUSE_SENSITIVE_META_KEY]: true } : {}),
-        ...(options.kind ? { [APIFUSE_SENSITIVE_KIND_META_KEY]: options.kind } : {}),
+        [APIFUSE_SENSITIVE_META_KEY]: isSensitive,
+        ...(kind !== undefined || APIFUSE_SENSITIVE_KIND_META_KEY in metadata
+            ? { [APIFUSE_SENSITIVE_KIND_META_KEY]: kind }
+            : {}),
     });
 }
 export function sensitive(schema, kind) {
     return field(schema, { sensitive: true, kind });
 }
+/**
+ * Declare a field as reviewed public data (business, facility, product, or
+ * place names and contacts) so a key-based privacy classifier hit counts as
+ * declared instead of undeclared. Emits `x-apifuse-sensitive: false` on the
+ * JSON Schema leaf; nothing is redacted. Use `sensitive()` for anything that
+ * identifies a person. Apply it to the leaf, before `.optional()` or
+ * `.nullable()`; wrapping a `sensitive()` declaration throws at definition time.
+ */
+export function publicField(schema) {
+    return field(schema, { sensitive: false });
+}
 function sensitiveString(kind, description, options = {}) {
     const schema = options.minLength === undefined ? z.string() : z.string().min(options.minLength);
     return field(schema, {
@@ -222,6 +264,34 @@ function readZodMetadata(schema) {
     const metadata = maybeMeta.call(schema);
     return metadata && typeof metadata === "object" ? metadata : undefined;
 }
+// Same-path wrappers (optional, nullable, default, catch, readonly, pipe,
+// lazy, ...) share the JSON Schema leaf with the schema they wrap.
+function wrapsSensitiveDeclaration(schema, seen = new Set()) {
+    const def = readZodDef(schema);
+    if (!def || seen.has(schema))
+        return false;
+    seen.add(schema);
+    return sameLeafChildren(def).some((child) => isSensitiveSchema(child) || wrapsSensitiveDeclaration(child, seen));
+}
+function sameLeafChildren(def) {
+    switch (Reflect.get(def, "type")) {
+        case "pipe":
+            return [Reflect.get(def, "in"), Reflect.get(def, "out")];
+        case "lazy": {
+            // A forward-reference getter can throw before its target is
+            // initialised; treat that as no declaration rather than failing.
+            const getter = Reflect.get(def, "getter");
+            try {
+                return typeof getter === "function" ? [getter()] : [];
+            }
+            catch {
+                return [];
+            }
+        }
+        default:
+            return [Reflect.get(def, "innerType")];
+    }
+}
 function readZodDef(schema) {
     if (!schema || typeof schema !== "object")
         return undefined;

package/dist/serve.d.ts

@@ -1 +1 @@
-export { createServerApp, type ServeOptions, serve } from "./server/serve.js";
+export { createServerApp, createServerAppAsync, type ServeOptions, serve, } from "./server/serve.js";

package/dist/serve.js

@@ -1 +1 @@
-export { createServerApp, serve } from "./server/serve.js";
+export { createServerApp, createServerAppAsync, serve, } from "./server/serve.js";

package/dist/server/error-observability.d.ts

@@ -0,0 +1 @@
+export { safeProviderErrorObservability } from "../error-observability.js";

package/dist/server/error-observability.js

@@ -0,0 +1 @@
+export { safeProviderErrorObservability } from "../error-observability.js";

package/dist/server/error-stack-frames.d.ts

@@ -0,0 +1,35 @@
+import { type DiagnosticRedactor } from "../runtime/diagnostic-redactor.js";
+/**
+ * Bounded, whitelist-shaped stack frames for masked (>=500) provider failures.
+ *
+ * `sanitizeDiagnosticText` is a blacklist scrubber for free text: a V8/Bun
+ * frame such as `at inner (/srv/app/probe.ts:3:30)` comes out as
+ * `at inner ([REDACTED])`, and even a bare `serve-implementation.ts:2039:12`
+ * trips the opaque-token heuristics. Stack frames therefore never go through
+ * it. Instead each frame is parsed against a strict grammar and re-emitted
+ * from its parts only: an optional `async`/`new` marker, the function name
+ * (identifier characters only), the file *basename* (never a filesystem
+ * directory, URL, or drive letter) and the numeric line:column. The sole
+ * exception is an engine-internal location (`native`, or a `node:` module id
+ * of identifier-shaped segments), which is kept verbatim because it names no
+ * deployment path. Frames that do not fit the grammar (eval frames, frames
+ * without a location, oversized lines) are dropped rather than passed
+ * through.
+ */
+export declare const MAX_PROVIDER_ERROR_STACK_FRAMES = 5;
+/** Parses one `at ...` line into `[async |new ][fn ](basename:line:col)`, or undefined. */
+export declare function parseProviderErrorStackFrame(line: string): string | undefined;
+/**
+ * Up to {@link MAX_PROVIDER_ERROR_STACK_FRAMES} whitelist-shaped frames from
+ * `error.stack`, or undefined when nothing parses. For an engine-formatted
+ * stack the header (which embeds the current `message`) is located and
+ * stripped first, so a provider-controlled *message* containing newlines
+ * cannot inject frame-shaped text (no header match, no frames). A provider
+ * that overwrites `stack` or `name` outright can still put grammar-shaped
+ * frames in the record: the field is a diagnostic hint, not an attested
+ * location, and the whitelist plus the redactor bound what it can carry.
+ * Each emitted frame still passes
+ * through the request redactor so a registered secret that happens to appear
+ * in a function or file name is masked (fail-closed to `[REDACTION_FAILED]`).
+ */
+export declare function providerErrorStackFrames(error: unknown, redact?: DiagnosticRedactor): string[] | undefined;

package/dist/server/error-stack-frames.js

@@ -0,0 +1,219 @@
+import { redactDiagnosticText } from "../runtime/diagnostic-redactor.js";
+/**
+ * Bounded, whitelist-shaped stack frames for masked (>=500) provider failures.
+ *
+ * `sanitizeDiagnosticText` is a blacklist scrubber for free text: a V8/Bun
+ * frame such as `at inner (/srv/app/probe.ts:3:30)` comes out as
+ * `at inner ([REDACTED])`, and even a bare `serve-implementation.ts:2039:12`
+ * trips the opaque-token heuristics. Stack frames therefore never go through
+ * it. Instead each frame is parsed against a strict grammar and re-emitted
+ * from its parts only: an optional `async`/`new` marker, the function name
+ * (identifier characters only), the file *basename* (never a filesystem
+ * directory, URL, or drive letter) and the numeric line:column. The sole
+ * exception is an engine-internal location (`native`, or a `node:` module id
+ * of identifier-shaped segments), which is kept verbatim because it names no
+ * deployment path. Frames that do not fit the grammar (eval frames, frames
+ * without a location, oversized lines) are dropped rather than passed
+ * through.
+ */
+export const MAX_PROVIDER_ERROR_STACK_FRAMES = 5;
+const MAX_STACK_SCAN_CHARS = 16 * 1024;
+const MAX_STACK_SCAN_LINES = 64;
+const MAX_STACK_LINE_CHARS = 1024;
+const FRAME_LINE = /^\s+at\s+(\S.*)$/;
+const FRAME_MODIFIER = /^(async|new)\s+(.*)$/;
+const FRAME_FUNCTION_NAME = /^[\w$.<>[\] #]{1,80}$/;
+const FRAME_LOCATION = /^(.*):(\d{1,7}):(\d{1,7})$/;
+const MAX_NODE_MODULE_ID_CHARS = 128;
+// Engine-internal module ids only: `node:` plus `/`-separated identifier-shaped
+// segments (`node:async_hooks`, `node:internal/process/task_queues`). Every
+// segment must start with a letter or `_`, so `..` traversal and dotfile
+// segments cannot ride through this branch.
+const FRAME_NODE_MODULE = /^node:[A-Za-z_][\w.-]{0,40}(?:\/[A-Za-z_][\w.-]{0,40}){0,7}$/;
+const FRAME_BASENAME = /^[\w.$-]{1,120}$/;
+// A basename of dots only (`.`, `..`, `...`) names no file.
+const FRAME_BASENAME_HAS_NAME = /[^.]/;
+function parseFunctionName(raw) {
+    let rest = raw.trim();
+    let modifier;
+    const modified = FRAME_MODIFIER.exec(rest);
+    if (modified) {
+        modifier = modified[1];
+        rest = modified[2].trim();
+    }
+    if (rest.length === 0)
+        return { modifier };
+    if (!FRAME_FUNCTION_NAME.test(rest))
+        return undefined;
+    return { modifier, name: rest };
+}
+function parseLocation(raw) {
+    if (/[\s()]/.test(raw))
+        return undefined;
+    const located = FRAME_LOCATION.exec(raw);
+    if (!located)
+        return undefined;
+    const [, path, line, column] = located;
+    let file;
+    if (path === "native" ||
+        (path.length <= MAX_NODE_MODULE_ID_CHARS && FRAME_NODE_MODULE.test(path))) {
+        // Not filesystem paths: engine-internal module ids carry no deployment
+        // information. This is the one branch that keeps a `/`, and the grammar
+        // above bounds it to identifier segments.
+        file = path;
+    }
+    else {
+        const separator = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+        const basename = separator >= 0 ? path.slice(separator + 1) : path;
+        if (!FRAME_BASENAME.test(basename))
+            return undefined;
+        // `.` and `..` pass the basename character class but name no file: they
+        // are the traversal tokens the grammar exists to exclude, so a path such
+        // as `/srv/app/..:1:1` must not be emitted as `..:1:1`.
+        if (!FRAME_BASENAME_HAS_NAME.test(basename))
+            return undefined;
+        file = basename;
+    }
+    return `${file}:${line}:${column}`;
+}
+/** Parses one `at ...` line into `[async |new ][fn ](basename:line:col)`, or undefined. */
+export function parseProviderErrorStackFrame(line) {
+    if (line.length > MAX_STACK_LINE_CHARS)
+        return undefined;
+    const frame = FRAME_LINE.exec(line);
+    if (!frame)
+        return undefined;
+    const rest = frame[1].trimEnd();
+    let functionPart;
+    let locationPart;
+    if (rest.endsWith(")")) {
+        const open = rest.lastIndexOf("(");
+        if (open < 0)
+            return undefined;
+        functionPart = rest.slice(0, open);
+        locationPart = rest.slice(open + 1, -1);
+    }
+    else {
+        // A frame with no parenthesized location still carries its `async`/`new`
+        // modifier inline (`at async file:///app/index.mjs:12:3`, emitted by V8
+        // for an anonymous async frame such as a module's top-level await).
+        // Split it off here: `parseLocation` rejects anything containing
+        // whitespace, so leaving it attached dropped the whole frame.
+        const modified = FRAME_MODIFIER.exec(rest);
+        functionPart = modified ? modified[1] : "";
+        locationPart = modified ? modified[2].trim() : rest;
+    }
+    // Eval frames nest parentheses inside the function part; never pass them through.
+    if (/[()]/.test(functionPart))
+        return undefined;
+    const location = parseLocation(locationPart);
+    if (!location)
+        return undefined;
+    const fn = parseFunctionName(functionPart);
+    if (!fn)
+        return undefined;
+    const prefix = [fn.modifier, fn.name].filter((part) => part !== undefined).join(" ");
+    return prefix.length > 0 ? `${prefix} (${location})` : `(${location})`;
+}
+// V8 (Node >= 21) installs `stack` as a shared native accessor pair on every
+// Error instance; JSC (Bun) installs a data property. Capture the engine's own
+// accessor once so a provider-defined accessor (a different function object) is
+// still rejected while the engine's is trusted. The engine accessor itself can
+// call a process-global `Error.prepareStackTrace` hook, a process-wide trust
+// boundary this module cannot narrow: a provider that installs one already
+// reshapes `stack` for every consumer, and the whitelist grammar below still
+// bounds what the resulting text can carry.
+const NATIVE_STACK_GETTER = Object.getOwnPropertyDescriptor(new Error(), "stack")?.get;
+function readOwnStackString(error) {
+    // Only engine-captured stacks: a thrown plain object is provider-authored text.
+    if (!(error instanceof Error))
+        return undefined;
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(error, "stack");
+        if (descriptor === undefined)
+            return undefined;
+        let stack;
+        if (Object.hasOwn(descriptor, "value")) {
+            stack = descriptor.value;
+        }
+        else if (typeof NATIVE_STACK_GETTER === "function" &&
+            descriptor.get === NATIVE_STACK_GETTER) {
+            stack = Reflect.apply(NATIVE_STACK_GETTER, error, []);
+        }
+        else {
+            // A provider-defined accessor must never run inside the logger.
+            return undefined;
+        }
+        return typeof stack === "string" ? stack : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Header shapes ahead of the frame block: `Name: message` (V8/JSC),
+// `Name [CODE]: message` (node:assert), `Name` (empty message), or the bare
+// message (Playwright rewrites `stack` as message-first). The message itself
+// is matched verbatim, so anything before it must be a short name-like prefix.
+const HEADER_NAME_PREFIX = /^(?:[\w$][\w$ .[\]-]{0,119}: )?$/;
+const HEADER_NAME_ONLY = /^[\w$][\w$ .[\]-]{0,119}$/;
+/**
+ * The frame block that follows the header, or undefined when the header does
+ * not embed the current `message` followed by a newline. Fail closed there: if
+ * `message` was mutated after the stack was formatted, the original message
+ * lines are still in the string and could be parsed as forged frames. (A
+ * mutation that truncates exactly at one of the message's own newlines is
+ * indistinguishable from the string alone; the whitelist grammar and the
+ * redactor still bound what such a line can carry.)
+ */
+function frameBlock(stack, error) {
+    let message;
+    try {
+        message = error.message;
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof message !== "string")
+        return undefined;
+    if (message.length === 0) {
+        const newline = stack.indexOf("\n");
+        if (newline < 0 || !HEADER_NAME_ONLY.test(stack.slice(0, newline)))
+            return undefined;
+        return stack.slice(newline + 1);
+    }
+    const at = stack.indexOf(`${message}\n`);
+    if (at < 0 || !HEADER_NAME_PREFIX.test(stack.slice(0, at)))
+        return undefined;
+    return stack.slice(at + message.length + 1);
+}
+/**
+ * Up to {@link MAX_PROVIDER_ERROR_STACK_FRAMES} whitelist-shaped frames from
+ * `error.stack`, or undefined when nothing parses. For an engine-formatted
+ * stack the header (which embeds the current `message`) is located and
+ * stripped first, so a provider-controlled *message* containing newlines
+ * cannot inject frame-shaped text (no header match, no frames). A provider
+ * that overwrites `stack` or `name` outright can still put grammar-shaped
+ * frames in the record: the field is a diagnostic hint, not an attested
+ * location, and the whitelist plus the redactor bound what it can carry.
+ * Each emitted frame still passes
+ * through the request redactor so a registered secret that happens to appear
+ * in a function or file name is masked (fail-closed to `[REDACTION_FAILED]`).
+ */
+export function providerErrorStackFrames(error, redact) {
+    const stack = readOwnStackString(error);
+    if (stack === undefined)
+        return undefined;
+    const body = frameBlock(stack, error);
+    if (body === undefined)
+        return undefined;
+    const frames = [];
+    const lines = body.slice(0, MAX_STACK_SCAN_CHARS).split("\n", MAX_STACK_SCAN_LINES);
+    for (const line of lines) {
+        if (frames.length >= MAX_PROVIDER_ERROR_STACK_FRAMES)
+            break;
+        const frame = parseProviderErrorStackFrame(line);
+        if (frame !== undefined)
+            frames.push(redactDiagnosticText(frame, redact));
+    }
+    return frames.length > 0 ? frames : undefined;
+}

package/dist/server/index.d.ts

@@ -1,7 +1,26 @@
-export { createServerApp, type ServeOptions, serve } from "./serve.js";
+export type { ProviderLocaleCatalogMap } from "../i18n/catalog.js";
+export type { ProviderLocale, ProviderLocaleCatalog } from "../i18n/keys.js";
+export type { ProxyCacheStatus, ProxyProtocol, ProxyUserAgentSource, ProxyVendorName, SmartproxyAllocatorBodyClass, } from "../config/loader.js";
+export type { ProxyTelemetryHeaderPayload, ProxyHash, ProxyTelemetryLogPayload, ProxyTelemetryResolvedPayload, ProxyTelemetryUnresolvedPayload, } from "../runtime/proxy-telemetry.js";
+export { RequestTelemetry, closedEnum, type ClosedEnum, type GatewayIngestible, type RequestTelemetryLogPayload, type SpanIndex, type TelemetryContributor, type TelemetryKey, type TenantNeutral, } from "../runtime/request-telemetry.js";
+export { OcrTelemetryCollector, bindOcrTelemetry, type OcrTelemetryBackend, type OcrTelemetryEngine, type OcrTelemetryErrorCode, type OcrTelemetryEvent, type OcrTelemetryModel, type OcrTelemetryFinishReason, type OcrTelemetryHeaderPayload, type OcrTelemetryLogPayload, type OcrTelemetrySink, } from "../runtime/ocr-telemetry.js";
+export { ResolverTelemetryCollector, type ResolverAttemptSample, type ResolverCacheReadTelemetryEvent, type ResolverCacheWriteTelemetryEvent, type ResolverFailoverTelemetryEvent, type ResolverIdentityTelemetryEvent, type ResolverOutcomeTelemetryEvent, type ResolverTelemetryAttemptOutcome, type ResolverTelemetryCacheStatus, type ResolverTelemetryCacheWriteReason, type ResolverTelemetryErrorClass, type ResolverTelemetryHeaderPayload, type ResolverTelemetryIdentitySource, type ResolverTelemetryLogPayload, type ResolverTelemetryOutcome, type ResolverTelemetryPhase, type ResolverTelemetrySink, type ResolverVendorAttemptTelemetryEvent, } from "../runtime/resolver-telemetry.js";
+export { StealthTelemetryCollector, type StealthTelemetryAttemptEvent, type StealthTelemetryAttemptKind, type StealthTelemetryAttemptSample, type StealthTelemetryDiagnostics, type StealthTelemetryErrorCode, type StealthTelemetryHeaderPayload, type StealthTelemetryLogPayload, type StealthTelemetryRequestClass, type StealthTelemetrySbsdEvent, type StealthTelemetrySbsdOutcome, type StealthTelemetrySink, } from "../runtime/stealth-telemetry.js";
+export { SttTelemetryCollector, bindSttTelemetry, type SttTelemetryBackend, type SttTelemetryEngine, type SttTelemetryErrorCode, type SttTelemetryEvent, type SttTelemetryModel, type SttTelemetryHeaderPayload, type SttTelemetryLogPayload, type SttTelemetrySink, } from "../runtime/stt-telemetry.js";
+export { BrowserTelemetryCollector, type BrowserTelemetryErrorCode, type BrowserTelemetryHeaderPayload, type BrowserTelemetryLogPayload, type BrowserTelemetryPoolAcquireOutcome, type BrowserTelemetrySink, type BrowserTelemetrySampleName, type BrowserTelemetryEngine, } from "../runtime/browser-telemetry.js";
+export type { ResolverVendorUnavailableReason } from "../runtime/resolver-vendors/types.js";
+export type { Span, TraceContext } from "../runtime/trace.js";
+export type { StealthBrowser, StealthOS, StealthProfileDescriptor } from "../types.js";
+export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ErrorObservabilityDetails, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderErrorCauseFrame, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
+export type { ProviderStateBackendLogEvent, ProviderStoreBackendReport, } from "./state-backend-report.js";
+export type { ProviderErrorObservability } from "../errors.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
-export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens.js";
+export { type InputDateTokenCalendar, resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";
+export { type CollectRuntimeDiagnosticsInput, collectRuntimeDiagnostics, DEFAULT_PROCFS_SELF_ROOT, DEFAULT_RUNTIME_DIAGNOSTICS_WINDOW_MS, MAX_RUNTIME_DIAGNOSTICS_WINDOW_MS, MIN_RUNTIME_DIAGNOSTICS_WINDOW_MS, normalizeRuntimeDiagnosticsWindowMs, PROCFS_CLOCK_TICKS_PER_SECOND, resolveRuntimeDiagnosticsWindowMs, RUNTIME_DIAGNOSTICS_ROUTE, RUNTIME_DIAGNOSTICS_SCHEMA_VERSION, RUNTIME_DIAGNOSTICS_WINDOW_QUERY, type RuntimeDiagnosticsActiveResources, type RuntimeDiagnosticsClock, type RuntimeDiagnosticsCpu, type RuntimeDiagnosticsCpuTotals, type RuntimeDiagnosticsEventLoop, type RuntimeDiagnosticsEventLoopUtilization, type RuntimeDiagnosticsFdKind, type RuntimeDiagnosticsMemory, type RuntimeDiagnosticsProcfs, type RuntimeDiagnosticsReport, type RuntimeDiagnosticsThread, type RuntimeDiagnosticsThreadContextSwitches, type RuntimeDiagnosticsThreadCpuTicks, type RuntimeDiagnosticsThreadWindow, } from "./runtime-diagnostics.js";
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, type SelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";
 export type { AuthFlowRequest, AuthFlowResponse, AuthFlowSuccessResponse, ConnectionMode, OperationConnection, OperationErrorResponse, OperationRequest, OperationResponse, OperationSuccessResponse, } from "./types.js";
 export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types.js";
+export { HttpTelemetryCollector, type HttpTelemetrySink, type HttpTelemetryRequestSink, type HttpAttemptTelemetryEvent, type HttpAttemptSample, type HttpTelemetryErrorCode, type HttpTelemetryRetryPayload, type HttpTelemetryLogPayload, type HttpTelemetryHeaderPayload, } from "../runtime/http-telemetry.js";
+export type { HttpRetrySummary } from "../types.js";
+export { NativeTelemetryCollector, type NativeAttemptSample, type NativeConnectTelemetryEvent, type NativeLifecycleTelemetryEvent, type NativeTelemetryDiagnostics, type NativeTelemetryErrorCode, type NativeTelemetryHeaderPayload, type NativeTelemetryKind, type NativeTelemetryLifecycleKind, type NativeTelemetryLogPayload, type NativeTelemetryOutcome, type NativeTelemetrySink, type NativeTelemetryVendorSkipReason, type NativeVendorSkipTelemetryEvent, } from "../runtime/native-telemetry.js";

package/dist/server/index.js

@@ -1,6 +1,15 @@
-export { createServerApp, serve } from "./serve.js";
+export { RequestTelemetry, closedEnum, } from "../runtime/request-telemetry.js";
+export { OcrTelemetryCollector, bindOcrTelemetry, } from "../runtime/ocr-telemetry.js";
+export { ResolverTelemetryCollector, } from "../runtime/resolver-telemetry.js";
+export { StealthTelemetryCollector, } from "../runtime/stealth-telemetry.js";
+export { SttTelemetryCollector, bindSttTelemetry, } from "../runtime/stt-telemetry.js";
+export { BrowserTelemetryCollector, } from "../runtime/browser-telemetry.js";
+export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, serve, } from "./serve.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, SelfTestRequestSchema, } from "./self-test.js";
-export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens.js";
+export { resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";
+export { collectRuntimeDiagnostics, DEFAULT_PROCFS_SELF_ROOT, DEFAULT_RUNTIME_DIAGNOSTICS_WINDOW_MS, MAX_RUNTIME_DIAGNOSTICS_WINDOW_MS, MIN_RUNTIME_DIAGNOSTICS_WINDOW_MS, normalizeRuntimeDiagnosticsWindowMs, PROCFS_CLOCK_TICKS_PER_SECOND, resolveRuntimeDiagnosticsWindowMs, RUNTIME_DIAGNOSTICS_ROUTE, RUNTIME_DIAGNOSTICS_SCHEMA_VERSION, RUNTIME_DIAGNOSTICS_WINDOW_QUERY, } from "./runtime-diagnostics.js";
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";
 export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types.js";
+export { HttpTelemetryCollector, } from "../runtime/http-telemetry.js";
+export { NativeTelemetryCollector, } from "../runtime/native-telemetry.js";

package/dist/server/runtime-diagnostics.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Internal runtime diagnostics route on the provider's primary listener, next
+ * to `/health` and `/readyz`. It answers one JSON report that tells an idle
+ * process that still burns CPU apart from a busy one without `exec`: process
+ * CPU sampled over a short window, memory, the Node event-loop and
+ * active-resource APIs, and on Linux the per-thread CPU and file-descriptor
+ * picture from `/proc/self`.
+ *
+ * Read-only and secret-free. It shares the boundary of `/health` and `/readyz`:
+ * the generated provider NetworkPolicy admits only the gateway on this port and
+ * the gateway dials canonical operation paths only, so a tenant cannot reach
+ * it; operators use `kubectl port-forward`.
+ */
+export declare const RUNTIME_DIAGNOSTICS_ROUTE = "/__apifuse/diagnostics/runtime";
+export declare const RUNTIME_DIAGNOSTICS_SCHEMA_VERSION: 1;
+/** Query parameter naming the sampling window; clamped, never rejected. */
+export declare const RUNTIME_DIAGNOSTICS_WINDOW_QUERY = "windowMs";
+export declare const DEFAULT_RUNTIME_DIAGNOSTICS_WINDOW_MS = 250;
+export declare const MIN_RUNTIME_DIAGNOSTICS_WINDOW_MS = 50;
+export declare const MAX_RUNTIME_DIAGNOSTICS_WINDOW_MS = 5000;
+/**
+ * Linux USER_HZ. The unit of `utime`/`stime` in `/proc` stat files is an ABI
+ * constant (100 Hz) independent of the kernel's CONFIG_HZ.
+ */
+export declare const PROCFS_CLOCK_TICKS_PER_SECOND = 100;
+export declare const DEFAULT_PROCFS_SELF_ROOT = "/proc/self";
+export interface RuntimeDiagnosticsCpuTotals {
+    readonly userMicros: number;
+    readonly systemMicros: number;
+}
+export interface RuntimeDiagnosticsCpu {
+    /** `process.cpuUsage()` since boot and its average in cores over `uptimeSeconds`. */
+    readonly lifetime: RuntimeDiagnosticsCpuTotals & {
+        readonly averageCores: number;
+    };
+    /** `process.cpuUsage()` delta over the sampling window, as cores (1 = one CPU fully busy). */
+    readonly window: RuntimeDiagnosticsCpuTotals & {
+        readonly userCores: number;
+        readonly systemCores: number;
+        readonly totalCores: number;
+    };
+}
+export interface RuntimeDiagnosticsEventLoopUtilization {
+    readonly idle: number;
+    readonly active: number;
+    readonly utilization: number;
+}
+export interface RuntimeDiagnosticsEventLoop {
+    /**
+     * false when the runtime returned only zeros for the whole process lifetime.
+     * Bun 1.2 and 1.3 stub `performance.eventLoopUtilization`; read
+     * `cpu.window` and `procfs.threads` instead.
+     */
+    readonly reported: boolean;
+    readonly lifetime: RuntimeDiagnosticsEventLoopUtilization;
+    readonly window: RuntimeDiagnosticsEventLoopUtilization;
+}
+export interface RuntimeDiagnosticsActiveResources {
+    /**
+     * false when the runtime listed nothing, although at least the socket that
+     * answers this request is alive. Bun 1.2 and 1.3 stub
+     * `process.getActiveResourcesInfo`; read `procfs.fileDescriptors` instead.
+     */
+    readonly reported: boolean;
+    readonly total: number;
+    readonly byType: Readonly<Record<string, number>>;
+}
+export interface RuntimeDiagnosticsMemory {
+    readonly rss: number;
+    readonly heapTotal: number;
+    readonly heapUsed: number;
+    readonly external: number;
+    readonly arrayBuffers: number;
+}
+export interface RuntimeDiagnosticsThreadCpuTicks {
+    readonly userTicks: number;
+    readonly systemTicks: number;
+}
+export interface RuntimeDiagnosticsThreadContextSwitches {
+    readonly voluntary: number;
+    readonly nonvoluntary: number;
+}
+export interface RuntimeDiagnosticsThreadWindow extends RuntimeDiagnosticsThreadCpuTicks {
+    /** CPU consumed by this thread over the window, in cores. */
+    readonly cores: number;
+    readonly contextSwitches: RuntimeDiagnosticsThreadContextSwitches;
+}
+export interface RuntimeDiagnosticsThread {
+    readonly tid: number;
+    /** Kernel thread name (`comm`, 15 bytes), e.g. `bun`, `HTTP Client`, `HeapHelper`. */
+    readonly name: string;
+    /** Scheduler state letter at the second sample (`R` running, `S` sleeping, ...). */
+    readonly state: string;
+    /** Kernel wait channel at the second sample (`0` while running); null when unreadable. */
+    readonly waitChannel: string | null;
+    readonly lifetime: RuntimeDiagnosticsThreadCpuTicks;
+    /** null for a thread that appeared after the first sample. */
+    readonly window: RuntimeDiagnosticsThreadWindow | null;
+}
+export type RuntimeDiagnosticsFdKind = "socket" | "eventpoll" | "timerfd" | "eventfd" | "pipe" | "file" | "other";
+export interface RuntimeDiagnosticsProcfs {
+    readonly clockTicksPerSecond: number;
+    /**
+     * Elapsed time between the two /proc/self scans. Slightly longer than
+     * `window.observedMs` because it encloses the scans themselves; thread
+     * `window.cores` is computed over this interval.
+     */
+    readonly observedMs: number;
+    readonly threads: {
+        readonly total: number;
+        readonly byName: Readonly<Record<string, number>>;
+        /** Sorted by window cores descending, so the hottest thread is first. */
+        readonly items: readonly RuntimeDiagnosticsThread[];
+    };
+    readonly fileDescriptors: {
+        readonly total: number;
+        readonly byKind: Readonly<Record<RuntimeDiagnosticsFdKind, number>>;
+    };
+}
+export interface RuntimeDiagnosticsReport {
+    readonly schemaVersion: typeof RUNTIME_DIAGNOSTICS_SCHEMA_VERSION;
+    readonly provider: {
+        readonly id: string;
+        readonly version: string;
+    };
+    readonly sdkVersion: string;
+    readonly runtime: {
+        readonly bunVersion: string | null;
+        readonly nodeCompatVersion: string;
+        readonly platform: string;
+        readonly arch: string;
+        readonly pid: number;
+    };
+    readonly sampledAt: string;
+    readonly uptimeSeconds: number;
+    readonly window: {
+        readonly requestedMs: number;
+        readonly observedMs: number;
+    };
+    readonly cpu: RuntimeDiagnosticsCpu;
+    readonly memory: RuntimeDiagnosticsMemory;
+    readonly eventLoop: RuntimeDiagnosticsEventLoop;
+    readonly activeResources: RuntimeDiagnosticsActiveResources;
+    /** null off Linux or when `/proc/self` is unreadable. */
+    readonly procfs: RuntimeDiagnosticsProcfs | null;
+}
+export interface RuntimeDiagnosticsClock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+export interface CollectRuntimeDiagnosticsInput {
+    readonly provider: {
+        readonly id: string;
+        readonly version: string;
+    };
+    /** Sampling window; clamped to [MIN, MAX]. */
+    readonly windowMs?: number;
+    /** `/proc/self` substitute for tests. */
+    readonly procfsRoot?: string;
+    readonly clock?: RuntimeDiagnosticsClock;
+}
+export declare function normalizeRuntimeDiagnosticsWindowMs(value: number | undefined): number;
+/** Parses the `windowMs` query value; anything unparsable falls back to the default. */
+export declare function resolveRuntimeDiagnosticsWindowMs(raw: string | undefined | null): number;
+export declare function collectRuntimeDiagnostics(input: CollectRuntimeDiagnosticsInput): Promise<RuntimeDiagnosticsReport>;