@superdurable/connectors-sdk 0.1.1 → 0.3.0

package/dist/textgen/index.js

@@ -0,0 +1,628 @@
+import {
+  validateQueryDefinition
+} from "../chunk-32YJXBE4.js";
+import {
+  SecretString
+} from "../chunk-QDMBAWXD.js";
+import {
+  newQueryBranch,
+  newQueryRetry
+} from "../chunk-BQGYGCOQ.js";
+import {
+  ProviderReportedError,
+  blockedOutcome,
+  canonicalizePortableSchema,
+  classifyError,
+  extractStructuredAnswer,
+  extractStructuredAnswerFromSchema,
+  invalidResponseOutcome,
+  jsonObjectInstruction,
+  providerRejectedOutcome,
+  quotaExhaustedOutcome,
+  retryOutcome,
+  temperatureAccepted,
+  temperatureNotAccepted,
+  temperatureRange,
+  transformSchemaForProvider,
+  validateStructuredOutputRules,
+  validateWireFormat
+} from "../chunk-466BPS3M.js";
+import {
+  AddressRefusal,
+  BodyTooLargeError,
+  ProviderStalledError,
+  ProviderTransportError,
+  isHeaderSafeCredential,
+  parseRetryAfter,
+  readErrorTokens,
+  sendProviderRequest,
+  validateBaseURL
+} from "../chunk-UWB627CI.js";
+import "../chunk-IHG6ADQG.js";
+
+// src/textgen/contract.ts
+var TextGenerationOperationID = "generateText";
+var GeneratedBranchID = "generated";
+var TruncatedBranchID = "truncated";
+var BlockedBranchID = "blocked";
+var ProviderRejectedBranchID = "providerRejected";
+var InvalidResponseBranchID = "invalidResponse";
+var DefectBranchID = "defect";
+function textGenerationBranchDefinitions() {
+  return [
+    { id: GeneratedBranchID, description: "The model finished normally and returned text." },
+    { id: TruncatedBranchID, description: "The model stopped at the output token limit and returned any partial text.", optional: true },
+    { id: BlockedBranchID, description: "The provider stopped the response for a content policy, or the model refused.", optional: true },
+    { id: ProviderRejectedBranchID, description: "The provider conclusively rejected the request, such as invalid credentials, an unknown model, or exhausted quota.", optional: true },
+    { id: InvalidResponseBranchID, description: "The provider returned a malformed, oversized, or unusable response, including structured output that does not match its schema.", optional: true },
+    { id: DefectBranchID, description: "Local input, connection configuration, or connector definition is invalid.", optional: true }
+  ];
+}
+function validatePortableRequest(request) {
+  const message = checkPortableRequest(request).error;
+  return message ? { kind: "VALIDATION", provider: "", operation: "", message } : void 0;
+}
+function checkPortableRequest(request) {
+  if (!Array.isArray(request.messages) || request.messages.length === 0) return { error: "at least one message is required" };
+  for (const message of request.messages) {
+    if (message.role !== "user" && message.role !== "assistant") return { error: "message role must be user or assistant" };
+    if (typeof message.text !== "string" || message.text === "") return { error: "every message requires text" };
+  }
+  if ((request.maxOutputTokens ?? 0) < 0) return { error: "maxOutputTokens cannot be negative" };
+  if (request.structuredOutput != null) {
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(request.structuredOutput.name)) return { error: "structured output name must match ^[A-Za-z0-9_-]{1,64}$" };
+    if (request.structuredOutput.schema === void 0 || request.structuredOutput.schema === null) return { error: "structured output schema is required" };
+    try {
+      return { schema: canonicalizePortableSchema(request.structuredOutput.schema) };
+    } catch (error) {
+      return { error: `structured output schema is not portable ${error instanceof Error ? error.message : ""}` };
+    }
+  }
+  return {};
+}
+function resolveModel(requestModel, connectionModel) {
+  return requestModel.trim() || connectionModel;
+}
+function validateModelID(rule, value) {
+  let model = value.trim();
+  if (rule === "body") {
+    if (!/^[\x21-\x7e]{1,256}$/.test(model)) throw new TypeError("model ID must be 1 to 256 printable ASCII characters without spaces");
+    return model;
+  }
+  if (rule === "pathSegment") {
+    if (model.startsWith("models/")) model = model.slice(7);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(model)) throw new TypeError('model ID must start with a letter or digit and contain at most 128 letters, digits, ".", "_", or "-"');
+    return model;
+  }
+  throw new TypeError("model ID rule is invalid");
+}
+
+// src/providerhttp/server_sent_events.ts
+var ServerSentEventDecoder = class {
+  #maxEventBytes;
+  #maxTotalBytes;
+  #totalBytes = 0;
+  #pending = Buffer.alloc(0);
+  #eventBytes = 0;
+  #dataLines = [];
+  #eventType = "";
+  constructor(maxEventBytes, maxTotalBytes = Number.MAX_SAFE_INTEGER) {
+    this.#maxEventBytes = maxEventBytes;
+    this.#maxTotalBytes = maxTotalBytes;
+  }
+  /** Decode complete events; false from onEvent stops the current response. */
+  feed(chunk, onEvent) {
+    this.#pending = Buffer.concat([this.#pending, chunk]);
+    for (; ; ) {
+      const newline = this.#pending.indexOf(10);
+      if (newline < 0) {
+        if (this.#totalBytes + this.#pending.length > this.#maxTotalBytes) throw new BodyTooLargeError();
+        if (this.#pending.length > this.#maxEventBytes + 2) throw new BodyTooLargeError();
+        return true;
+      }
+      this.#totalBytes += newline + 1;
+      if (this.#totalBytes > this.#maxTotalBytes) throw new BodyTooLargeError();
+      let line = this.#pending.subarray(0, newline);
+      this.#pending = this.#pending.subarray(newline + 1);
+      const hasCR = line.at(-1) === 13;
+      if (hasCR) line = line.subarray(0, line.length - 1);
+      if (line.length > this.#maxEventBytes + (hasCR ? 0 : 1)) throw new BodyTooLargeError();
+      if (line.length === 0) {
+        if (this.#dataLines.length > 0) {
+          const event = { data: this.#dataLines.join("\n"), ...this.#eventType ? { event: this.#eventType } : {} };
+          this.#resetEvent();
+          if (onEvent(event) === false) return false;
+        } else this.#resetEvent();
+        continue;
+      }
+      if (line[0] === 58) continue;
+      this.#eventBytes += line.length;
+      if (this.#eventBytes > this.#maxEventBytes) throw new BodyTooLargeError();
+      const colon = line.indexOf(58);
+      const field = (colon < 0 ? line : line.subarray(0, colon)).toString("utf8");
+      let value = colon < 0 ? Buffer.alloc(0) : line.subarray(colon + 1);
+      if (value[0] === 32) value = value.subarray(1);
+      if (field === "data") this.#dataLines.push(value.toString("utf8"));
+      if (field === "event") this.#eventType = value.toString("utf8");
+    }
+  }
+  #resetEvent() {
+    this.#eventBytes = 0;
+    this.#dataLines = [];
+    this.#eventType = "";
+  }
+};
+
+// src/textgen/query.ts
+var safeToken = /^[A-Za-z0-9_.:-]{1,64}$/;
+var headerName = /^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$/;
+var heartbeatIntervalMs = 5e3;
+var TextStreamWriteError = class extends Error {
+};
+var LocalDefectError = class extends Error {
+};
+var TextGenerationQuery = class {
+  #definition;
+  #wireFormat;
+  #baseURL;
+  #connectionModel;
+  #requestTimeoutMs;
+  #httpClient;
+  #resolveCredential;
+  #maxResponseBytes;
+  #maxStreamEventBytes;
+  /** Validate configuration before a provider request can be made. */
+  constructor(config) {
+    if (!config) throw new TypeError("text generation query config is required");
+    validateQueryDefinition(config.definition);
+    if (config.definition.operation.operationId !== TextGenerationOperationID) throw new TypeError('text generation query definition must use operation ID "generateText"');
+    const expected = textGenerationBranchDefinitions();
+    if (config.definition.branches.length !== expected.length) throw new TypeError("generateText must declare exactly six branches");
+    for (const branch of expected) if (!config.definition.branches.some((actual) => actual.id === branch.id && !!actual.optional === !!branch.optional)) throw new TypeError(`generateText branch ${branch.id} has invalid optionality`);
+    if (config.definition.stepDefaults.executeDurability !== "sync") throw new TypeError("generateText must use sync Execute durability");
+    if (config.definition.stepDefaults.heartbeatTimeoutMs && config.definition.stepDefaults.heartbeatTimeoutMs < 2 * heartbeatIntervalMs) throw new TypeError("generateText heartbeat timeout must be zero or at least 10 seconds");
+    if (config.definition.stepDefaults.executeMethodTimeoutMs && config.definition.stepDefaults.executeMethodTimeoutMs <= config.requestTimeoutMs) throw new TypeError("generateText Execute timeout must exceed the request timeout");
+    validateWireFormat(config.wireFormat);
+    this.#wireFormat = {
+      ...config.wireFormat,
+      features: { ...config.wireFormat.features },
+      credentialHeader: { ...config.wireFormat.credentialHeader },
+      finishReasons: { ...config.wireFormat.finishReasons },
+      errorRules: [...config.wireFormat.errorRules ?? []],
+      errorTokenPointers: [...config.wireFormat.errorTokenPointers ?? []],
+      requestIDHeaders: [...config.wireFormat.requestIDHeaders ?? []],
+      rateLimitHeaders: [...config.wireFormat.rateLimitHeaders ?? []]
+    };
+    this.#baseURL = validateBaseURL(config.baseURL);
+    this.#connectionModel = (config.connectionModel ?? "").trim();
+    if (this.#connectionModel) validateModelID(this.#wireFormat.modelIDRule, this.#connectionModel);
+    if (!Number.isSafeInteger(config.requestTimeoutMs) || config.requestTimeoutMs <= 0) throw new TypeError("text generation query request timeout must be positive");
+    if (!config.resolveCredential) throw new TypeError("text generation query credential resolver is required");
+    if (!Number.isSafeInteger(config.maxResponseBytes) || config.maxResponseBytes < 1) throw new TypeError("text generation query maxResponseBytes must be positive");
+    if (this.#wireFormat.decodeStreamEvent && (!Number.isSafeInteger(config.maxStreamEventBytes) || (config.maxStreamEventBytes ?? 0) < 1)) {
+      throw new TypeError("text generation query maxStreamEventBytes must be positive for a streaming wire format");
+    }
+    this.#definition = config.definition;
+    this.#requestTimeoutMs = config.requestTimeoutMs;
+    this.#httpClient = config.httpClient;
+    this.#resolveCredential = config.resolveCredential;
+    this.#maxResponseBytes = config.maxResponseBytes;
+    this.#maxStreamEventBytes = config.maxStreamEventBytes ?? 0;
+  }
+  /** Return the connector's generateText definition. */
+  definition() {
+    return this.#definition;
+  }
+  /** Return optional request features declared by the provider. */
+  requestFeatures() {
+    return this.#wireFormat.features;
+  }
+  /** Return the provider model ID rule. */
+  modelIDRule() {
+    return this.#wireFormat.modelIDRule;
+  }
+  /** Validate in fixed order, dispatch once, and classify a branch or safe retry without exposing secrets. */
+  async invoke(call, request) {
+    const response = emptyResponse();
+    const format = this.#wireFormat;
+    const attempt = new TextGenerationAttemptResult(format, response);
+    if (!call?.context) return attempt.branch(DefectBranchID, "LOCAL_DEFECT", "a Dex Step context is required");
+    let schema;
+    let rules;
+    let encoded;
+    let credential;
+    try {
+      const model = resolveModel(request.model ?? "", this.#connectionModel);
+      if (!model) throw new TypeError("no model is selected; set the request Model or the connection model");
+      response.requestedModel = validateModelID(format.modelIDRule, model);
+      const portable = checkPortableRequest(request);
+      if (portable.error) throw new TypeError(portable.error);
+      schema = portable.schema;
+      validateFeatures(request, format.features);
+      rules = format.rulesForModel(response.requestedModel);
+      validateSampling(request, rules);
+      const prepared = { ...request, model: response.requestedModel };
+      if (request.structuredOutput && schema) {
+        try {
+          validateStructuredOutputRules(rules.structuredOutput);
+        } catch (error) {
+          throw new LocalDefectError(`the wire format's structured output rules are invalid: ${error instanceof Error ? error.message : ""}`);
+        }
+        if (rules.structuredOutput.mode === "none") throw new TypeError("the model does not support structured output");
+        if (rules.structuredOutput.mode === "jsonObjectWithInstruction" && !format.features.supportsInstructions) throw new LocalDefectError("the JSON object mode requires the Instructions feature");
+        prepared.structuredOutput = { ...request.structuredOutput, schema: transformSchemaForProvider(schema, rules.structuredOutput) };
+        if (rules.structuredOutput.mode === "jsonObjectWithInstruction") {
+          const instruction = jsonObjectInstruction(request.structuredOutput.name, request.structuredOutput.description ?? "", schema);
+          prepared.instructions = `${request.instructions ? `${request.instructions}
+
+` : ""}${instruction}`;
+        }
+      }
+      try {
+        const resolved = await this.#resolveCredential(call);
+        credential = resolved instanceof SecretString ? resolved.reveal() : resolved;
+      } catch {
+        return attempt.branch(DefectBranchID, "AUTHENTICATION", "connection credentials are unavailable");
+      }
+      if (!isHeaderSafeCredential(credential)) return attempt.branch(DefectBranchID, "AUTHENTICATION", "connection credentials are invalid");
+      try {
+        encoded = format.encodeRequest({ request: prepared, rules });
+      } catch (error) {
+        return attempt.branch(DefectBranchID, "VALIDATION", `the request cannot be encoded for the provider: ${error instanceof Error ? error.message : "invalid request"}`);
+      }
+      try {
+        validateEncodedRequest(encoded, format.credentialHeader.name);
+      } catch (error) {
+        throw new LocalDefectError(`the wire format built an invalid request: ${error instanceof Error ? error.message : ""}`);
+      }
+      if (encoded.isStreaming && !format.decodeStreamEvent || !encoded.isStreaming && !format.decodeResponse) return attempt.branch(DefectBranchID, "LOCAL_DEFECT", "the wire format cannot decode the response form it requested");
+    } catch (error) {
+      return attempt.branch(DefectBranchID, error instanceof LocalDefectError ? "LOCAL_DEFECT" : "VALIDATION", error instanceof Error ? error.message : "invalid request");
+    }
+    const headers = {
+      ...encoded.headers,
+      "Content-Type": "application/json",
+      Accept: encoded.isStreaming ? "text/event-stream" : "application/json",
+      [format.credentialHeader.name]: format.credentialHeader.prefix + credential
+    };
+    const stream = new TextGenerationStreamAttempt(call, format, encoded.isStreaming, this.#maxStreamEventBytes, this.#maxResponseBytes);
+    let hasCompleteResponse = false;
+    const heartbeats = new TextGenerationHeartbeat(call);
+    heartbeats.start();
+    try {
+      const providerRequest = {
+        url: this.#baseURL + encoded.path,
+        method: "POST",
+        headers,
+        body: encoded.body,
+        maxResponseBytes: this.#maxResponseBytes,
+        maxErrorResponseBytes: 64 << 10,
+        ignoreErrorBodyReadFailure: true,
+        addressPolicy: "unrestricted",
+        timeoutMs: this.#requestTimeoutMs,
+        signal: call.context.cancellationSignal,
+        ...format.stallTimeoutMs ? { stallTimeoutMs: format.stallTimeoutMs } : {},
+        onResponseChunk: stream.onChunk.bind(stream)
+      };
+      const providerResponse = await (this.#httpClient ? this.#httpClient.send(providerRequest) : sendProviderRequest(providerRequest));
+      hasCompleteResponse = true;
+      const receipt = makeReceipt(call, format, providerResponse.headers, credential);
+      const status = providerResponse.status;
+      stream.wasEventStream = encoded.isStreaming && isEventStream(providerResponse.headers);
+      if (status < 200 || status >= 300) {
+        const tokens = safeTokens(readErrorTokens(providerResponse.body.slice(0, 64 << 10), format.errorTokenPointers ?? []), credential);
+        const outcome = classifyError(format.errorRules ?? [], status, tokens);
+        let delay = 0;
+        if (outcome.disposition === "retry") {
+          try {
+            const providerDelay = format.readErrorRetryDelay?.(providerResponse.body);
+            if (typeof providerDelay === "number" && Number.isFinite(providerDelay) && providerDelay > 0) delay = providerDelay;
+          } catch {
+          }
+          if (!delay) delay = parseRetryAfter(String(providerResponse.headers["retry-after"] ?? ""));
+        }
+        return classifyOutcome(outcome, `provider returned HTTP ${status}${tokens.length ? ` ${tokens.join(" ")}` : ""}`, delay, receipt, attempt);
+      }
+      let decoded;
+      try {
+        if (stream.wasEventStream) {
+          if (!stream.hasObservedChunk) stream.onChunk(providerResponse.body, status, providerResponse.headers);
+          if (stream.error) throw stream.error;
+          if (!stream.state.isDone && !stream.state.hasFinished) return attempt.retry("TRANSPORT", "provider response ended before it was complete");
+          decoded = stream.state.response;
+        } else {
+          if (!format.decodeResponse) return attempt.branch(InvalidResponseBranchID, "PROTOCOL", "provider did not return the event stream it was asked for", receipt);
+          decoded = format.decodeResponse(providerResponse.body);
+        }
+      } catch (error) {
+        if (error instanceof ProviderReportedError) {
+          const tokens = safeTokens(error.errorTokens, credential);
+          return classifyOutcome(classifyError(format.errorRules ?? [], 0, tokens, true), `provider reported an error inside a 2xx response${tokens.length ? ` ${tokens.join(" ")}` : ""}`, 0, receipt, attempt);
+        }
+        if (error instanceof BodyTooLargeError) return attempt.branch(InvalidResponseBranchID, "RESPONSE_TOO_LARGE", "provider response exceeds the configured size limit", receipt);
+        if (error instanceof TextStreamWriteError) return attempt.retry("AVAILABILITY", "the text stream could not be written");
+        return attempt.branch(InvalidResponseBranchID, "PROTOCOL", "provider response does not match its documented format", receipt);
+      }
+      if (!isDecodedResponse(decoded)) return attempt.branch(InvalidResponseBranchID, "PROTOCOL", "provider response does not match its documented format", receipt);
+      if (!boundedIdentifier(decoded.servedModel ?? "") || !boundedIdentifier(decoded.responseId ?? "") || revealsCredential(decoded.servedModel ?? "", credential) || revealsCredential(decoded.responseId ?? "", credential)) {
+        return attempt.branch(InvalidResponseBranchID, "PROTOCOL", "provider returned an invalid model or response identifier", receipt);
+      }
+      response.servedModel = decoded.servedModel ?? "";
+      response.responseId = decoded.responseId ?? "";
+      if (response.responseId) receipt.providerObjectId = response.responseId;
+      const usage = completeUsage(decoded.usage ?? {});
+      if (!usage) return attempt.branch(InvalidResponseBranchID, "PROTOCOL", "provider reported negative token usage", receipt);
+      response.usage = usage;
+      const token = decoded.providerFinishReason ?? "";
+      if (revealsCredential(token, credential)) return attempt.branch(InvalidResponseBranchID, "PROTOCOL", "provider returned an invalid finish reason", receipt);
+      if (safeToken.test(token)) response.providerFinishReason = token;
+      if (decoded.isRefusal) response.finishReason = "refusal";
+      else if (!response.providerFinishReason) return attempt.branch(InvalidResponseBranchID, "PROTOCOL", "provider returned no recognizable finish reason", receipt);
+      else {
+        const reason = Object.hasOwn(format.finishReasons, response.providerFinishReason) ? format.finishReasons[response.providerFinishReason] : void 0;
+        if (!reason) return attempt.branch(InvalidResponseBranchID, "PROTOCOL", `provider stopped for an unsupported reason: ${response.providerFinishReason}`, receipt);
+        response.finishReason = reason;
+      }
+      const text = decoded.parts.filter((part) => !part.isReasoning).map((part) => part.text).join("");
+      if (response.finishReason === "stop") {
+        if (!text) return attempt.branch(InvalidResponseBranchID, "PROTOCOL", "provider finished without text", receipt);
+        try {
+          response.text = schema ? extractStructuredAnswerFromSchema(schema, text) : text;
+        } catch (error) {
+          return attempt.branch(InvalidResponseBranchID, "PROTOCOL", `structured output does not match its schema ${error instanceof Error ? error.message : ""}`, receipt);
+        }
+        if (!stream.wasEventStream && call.hasTextStream()) {
+          try {
+            call.writeText(response.text);
+          } catch {
+            return attempt.retry("AVAILABILITY", "the text stream could not be written");
+          }
+        }
+        return newQueryBranch(GeneratedBranchID, response, receipt);
+      }
+      if (response.finishReason === "length") {
+        response.text = text;
+        if (!stream.wasEventStream && text && call.hasTextStream()) {
+          try {
+            call.writeText(text);
+          } catch {
+            return attempt.retry("AVAILABILITY", "the text stream could not be written");
+          }
+        }
+        return newQueryBranch(TruncatedBranchID, response, receipt, attempt.failure("RESPONSE_TOO_LARGE", "provider stopped at the output token limit"));
+      }
+      return attempt.branch(BlockedBranchID, "PROVIDER_REJECTION", response.finishReason === "refusal" ? "the model refused the request" : "provider stopped the response for a content policy", receipt);
+    } catch (error) {
+      if (stream.error !== void 0) {
+        const receipt = stream.responseHeaders ? makeReceipt(call, format, stream.responseHeaders, credential) : void 0;
+        if (stream.error instanceof BodyTooLargeError) return attempt.branch(InvalidResponseBranchID, "RESPONSE_TOO_LARGE", "provider response exceeds the configured size limit", receipt);
+        if (stream.error instanceof TextStreamWriteError) return attempt.retry("AVAILABILITY", "the text stream could not be written");
+        if (stream.error instanceof ProviderReportedError) {
+          const tokens = safeTokens(stream.error.errorTokens, credential);
+          return classifyOutcome(
+            classifyError(format.errorRules ?? [], 0, tokens, true),
+            `provider reported an error inside a 2xx response${tokens.length ? ` ${tokens.join(" ")}` : ""}`,
+            0,
+            receipt ?? { provider: format.providerName },
+            attempt
+          );
+        }
+        return attempt.branch(InvalidResponseBranchID, "PROTOCOL", "provider response does not match its documented format", receipt);
+      }
+      if (error instanceof BodyTooLargeError) {
+        const receipt = error.headers ? makeReceipt(call, format, error.headers, credential) : void 0;
+        return attempt.branch(InvalidResponseBranchID, "RESPONSE_TOO_LARGE", "provider response exceeds the configured size limit", receipt);
+      }
+      if (error instanceof AddressRefusal) return attempt.branch(DefectBranchID, "LOCAL_DEFECT", "provider address is not allowed");
+      if (error instanceof ProviderStalledError) return attempt.retry("AVAILABILITY", "provider sent no bytes within the stall timeout");
+      if (error instanceof ProviderTransportError) return attempt.retry("TRANSPORT", error.isProvablyNotSent ? "provider request failed before a response was received" : "provider response ended before it was complete");
+      return hasCompleteResponse ? attempt.branch(InvalidResponseBranchID, "PROTOCOL", "provider response does not match its documented format") : attempt.retry("TRANSPORT", "provider response ended before it was complete");
+    } finally {
+      await heartbeats.stop();
+    }
+  }
+};
+var TextGenerationAttemptResult = class {
+  constructor(format, response) {
+    this.format = format;
+    this.response = response;
+  }
+  format;
+  response;
+  failure(kind, message) {
+    return { kind, provider: this.format.providerName, operation: TextGenerationOperationID, message };
+  }
+  branch(id, kind, message, receipt = { provider: this.format.providerName }) {
+    return newQueryBranch(id, this.response, receipt, this.failure(kind, message));
+  }
+  retry(kind, message, delay = 0) {
+    return newQueryRetry(this.failure(kind, message), delay);
+  }
+};
+var TextGenerationStreamAttempt = class {
+  constructor(call, format, isStreaming, maxEventBytes, maxTotalBytes) {
+    this.call = call;
+    this.format = format;
+    this.isStreaming = isStreaming;
+    this.#decoder = new ServerSentEventDecoder(maxEventBytes, maxTotalBytes);
+  }
+  call;
+  format;
+  isStreaming;
+  state = { response: { parts: [] }, hasFinished: false, isDone: false };
+  #decoder;
+  error;
+  wasEventStream = false;
+  hasObservedChunk = false;
+  responseHeaders;
+  onChunk(chunk, status, headers) {
+    if (status < 200 || status >= 300 || !this.isStreaming || !isEventStream(headers)) return;
+    this.wasEventStream = true;
+    this.hasObservedChunk = true;
+    this.responseHeaders = headers;
+    try {
+      return this.#decoder.feed(chunk, this.decodeEvent.bind(this));
+    } catch (error) {
+      this.error = error;
+      throw error;
+    }
+  }
+  decodeEvent(event) {
+    this.format.decodeStreamEvent?.(event, this.state, this.writeTextDelta.bind(this));
+    return !this.state.isDone;
+  }
+  writeTextDelta(delta) {
+    if (!delta || !this.call.hasTextStream()) return;
+    try {
+      this.call.writeText(delta);
+    } catch {
+      throw new TextStreamWriteError();
+    }
+  }
+};
+var TextGenerationHeartbeat = class {
+  constructor(call) {
+    this.call = call;
+  }
+  call;
+  #inFlight = Promise.resolve();
+  #timer;
+  start() {
+    this.#timer = setInterval(this.recordHeartbeat.bind(this), heartbeatIntervalMs);
+  }
+  async stop() {
+    if (this.#timer) clearInterval(this.#timer);
+    await this.#inFlight;
+  }
+  recordHeartbeat() {
+    this.#inFlight = this.#inFlight.then(async () => {
+      try {
+        await this.call.context.recordHeartbeat(void 0);
+      } catch {
+      }
+    });
+  }
+};
+function isEventStream(headers) {
+  return /^text\/event-stream(?:\s*;|$)/i.test(String(headers["content-type"] ?? "").trim());
+}
+function newTextGenerationQuery(config) {
+  return new TextGenerationQuery(config);
+}
+function emptyResponse() {
+  return {
+    text: "",
+    requestedModel: "",
+    servedModel: "",
+    responseId: "",
+    finishReason: "",
+    providerFinishReason: "",
+    usage: { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, reasoningTokens: 0, totalTokens: 0 }
+  };
+}
+function isDecodedResponse(value) {
+  if (value === null || typeof value !== "object") return false;
+  const response = value;
+  if (!Array.isArray(response.parts) || !response.parts.every((part) => part !== null && typeof part === "object" && typeof part.text === "string" && (part.isReasoning === void 0 || typeof part.isReasoning === "boolean"))) return false;
+  if (["servedModel", "responseId", "providerFinishReason"].some((name) => response[name] !== void 0 && typeof response[name] !== "string")) return false;
+  return (response.isRefusal === void 0 || typeof response.isRefusal === "boolean") && (response.usage === void 0 || response.usage !== null && typeof response.usage === "object" && !Array.isArray(response.usage));
+}
+function validateFeatures(request, features) {
+  const fields = [
+    [!!request.instructions, !!features.supportsInstructions, "Instructions"],
+    [!!request.structuredOutput, !!features.supportsStructuredOutput, "StructuredOutput"],
+    [!!request.maxOutputTokens, !!features.supportsMaxOutputTokens, "MaxOutputTokens"],
+    [request.temperature != null, !!features.supportsTemperature, "Temperature"],
+    [!!request.reasoningEffort, !!features.supportsReasoningEffort, "ReasoningEffort"]
+  ];
+  for (const [used, supported, name] of fields) if (used && !supported) throw new TypeError(`this connector's wire format does not send ${name}; leave it unset`);
+}
+function validateSampling(request, rules) {
+  if (request.temperature != null) {
+    const value = request.temperature;
+    if (!Number.isFinite(value) || value < 0) throw new TypeError("temperature must be a finite, non-negative number");
+    if (rules.temperature.kind === "notAccepted") throw new TypeError("the model does not accept a temperature; leave Temperature nil");
+    if (rules.temperature.kind === "range") {
+      if (!Number.isFinite(rules.temperature.minimum) || !Number.isFinite(rules.temperature.maximum) || rules.temperature.minimum > rules.temperature.maximum) throw new TypeError("the wire format's temperature range is invalid");
+      if (value < rules.temperature.minimum || value > rules.temperature.maximum) throw new TypeError(`the model accepts a temperature from ${rules.temperature.minimum} through ${rules.temperature.maximum}`);
+    }
+  }
+  if (request.reasoningEffort) {
+    if (!["none", "minimal", "low", "medium", "high", "xhigh", "max"].includes(request.reasoningEffort)) throw new TypeError("reasoning effort must be none, minimal, low, medium, high, xhigh, or max");
+    if (!(request.reasoningEffort in rules.reasoningEfforts)) throw new TypeError(`the model does not accept reasoning effort ${JSON.stringify(request.reasoningEffort)}`);
+  }
+}
+function validateEncodedRequest(encoded, credentialHeaderName) {
+  if (!encoded.path.startsWith("/")) throw new TypeError("encoded request path must start with /");
+  if (!/^[\x21-\x7e]+$/.test(encoded.path) || encoded.path.includes("#")) throw new TypeError("encoded request path must be printable ASCII without spaces or fragments");
+  const reserved = new Set([credentialHeaderName, "content-type", "content-length", "accept", "host"].map((value) => value.toLowerCase()));
+  for (const [name, value] of Object.entries(encoded.headers ?? {})) if (!headerName.test(name) || reserved.has(name.toLowerCase()) || !/^[\x20-\x7e]*$/.test(value)) throw new TypeError("encoded request header name or value is invalid");
+}
+function safeTokens(tokens, credential) {
+  return tokens.filter((token) => safeToken.test(token) && !revealsCredential(token, credential));
+}
+function revealsCredential(value, credential) {
+  return !!credential && value.includes(credential);
+}
+function boundedIdentifier(value) {
+  return value === "" || Buffer.byteLength(value) <= 256 && isHeaderSafeCredential(value);
+}
+function completeUsage(partial) {
+  const usage = { inputTokens: partial.inputTokens ?? 0, cachedInputTokens: partial.cachedInputTokens ?? 0, outputTokens: partial.outputTokens ?? 0, reasoningTokens: partial.reasoningTokens ?? 0, totalTokens: partial.totalTokens ?? 0 };
+  if (Object.values(usage).some((value) => !Number.isFinite(value) || value < 0)) return void 0;
+  if (usage.totalTokens === 0) usage.totalTokens = usage.inputTokens + usage.outputTokens;
+  return usage;
+}
+function makeReceipt(call, format, headers, credential) {
+  const receipt = { callId: call.id, provider: format.providerName, observedAt: (/* @__PURE__ */ new Date()).toISOString() };
+  for (const name of format.requestIDHeaders ?? []) {
+    const value = String(headers[name.toLowerCase()] ?? "").trim();
+    if (boundedIdentifier(value) && value && !revealsCredential(value, credential)) {
+      receipt.providerRequestId = value;
+      break;
+    }
+  }
+  for (const name of format.rateLimitHeaders ?? []) {
+    const value = String(headers[name.toLowerCase()] ?? "").trim();
+    if (value && value.length <= 256 && /^[\x20-\x7e]*$/.test(value) && !revealsCredential(value, credential)) {
+      (receipt.metadata ??= {})[name.toLowerCase()] = value;
+    }
+  }
+  return receipt;
+}
+function classifyOutcome(outcome, message, delay, receipt, attempt) {
+  if (outcome.disposition === "retry") return attempt.retry(outcome.kind, message, Number.isFinite(delay) ? Math.floor(Math.min(36e5, Math.max(0, delay))) : 0);
+  if (outcome.disposition === "blocked") {
+    attempt.response.finishReason = "contentPolicy";
+    return attempt.branch(BlockedBranchID, outcome.kind, message, receipt);
+  }
+  return attempt.branch(outcome.disposition === "invalidResponse" ? InvalidResponseBranchID : ProviderRejectedBranchID, outcome.kind, message, receipt);
+}
+export {
+  BlockedBranchID,
+  DefectBranchID,
+  GeneratedBranchID,
+  InvalidResponseBranchID,
+  ProviderRejectedBranchID,
+  ProviderReportedError,
+  TextGenerationOperationID,
+  TextGenerationQuery,
+  TruncatedBranchID,
+  blockedOutcome,
+  classifyError,
+  extractStructuredAnswer,
+  invalidResponseOutcome,
+  newTextGenerationQuery,
+  providerRejectedOutcome,
+  quotaExhaustedOutcome,
+  resolveModel,
+  retryOutcome,
+  temperatureAccepted,
+  temperatureNotAccepted,
+  temperatureRange,
+  textGenerationBranchDefinitions,
+  validateModelID,
+  validatePortableRequest,
+  validateStructuredOutputRules,
+  validateWireFormat
+};

package/dist/textgen/openaichat/index.d.ts

@@ -0,0 +1,44 @@
+import { o as TemperaturePolicy, R as ReasoningEffort, n as StructuredOutputRules, C as CredentialHeader, F as FinishReason, d as ErrorRule, W as WireFormat } from '../../wire_format-stEVruMs.js';
+import '../../types-D6De3sry.js';
+import 'zod';
+
+/** Role used for instructions in Chat Completions. */ type InstructionsRole = 'system' | 'developer';
+/** Token limit field accepted by this provider. */ type MaxTokensField = 'max_tokens' | 'max_completion_tokens';
+/** Whether requests use Chat Completions event streams. */ type StreamingPolicy = 'never' | 'always';
+/** First matching model rule overrides profile settings. */
+interface ModelRule {
+    /** Exact leading model ID text. */ modelIDPrefix?: string;
+    /** Anchored model ID regular expression. */ modelIDPattern?: string;
+    /** Sampling override. */ temperature?: TemperaturePolicy;
+    /** Accepted effort override; empty rejects all. */ reasoningEfforts?: Partial<Record<ReasoningEffort, string>>;
+    /** Schema mode override. */ structuredOutput?: StructuredOutputRules;
+    /** Token field override. */ maxTokensField?: MaxTokensField;
+    /** Streaming override. */ streaming?: StreamingPolicy;
+}
+/** Declarative provider Chat Completions dialect. */
+interface Profile {
+    /** Provider identity in failures. */ providerName: string;
+    /** Endpoint path; defaults to /chat/completions. */ chatCompletionsPath?: string;
+    /** Credential header; defaults to Authorization: Bearer. */ credentialHeader?: CredentialHeader;
+    /** Public fixed request headers. */ fixedHeaders?: Record<string, string>;
+    /** Instruction role; defaults to system. */ instructionsRole?: InstructionsRole;
+    /** Token field; defaults to max_tokens. */ maxTokensField?: MaxTokensField;
+    /** Accepted reasoning values. */ reasoningEfforts?: Partial<Record<ReasoningEffort, string>>;
+    /** Sampling policy; defaults to accepted. */ temperature?: TemperaturePolicy;
+    /** Structured output rules; defaults to none. */ structuredOutput?: StructuredOutputRules;
+    /** Send strict true in JSON schema mode. */ shouldSendStrictJSONSchema?: boolean;
+    /** Streaming policy; defaults to never. */ streaming?: StreamingPolicy;
+    /** Request usage with stream_options. */ shouldRequestStreamUsage?: boolean;
+    /** Optional allowlist of top-level body fields. */ allowedRequestFields?: string[];
+    /** Provider finish-token overrides. */ finishReasons?: Record<string, FinishReason>;
+    /** Error classification rules. */ errorRules?: ErrorRule[];
+    /** JSON pointers of safe error tokens. */ errorTokenPointers?: string[];
+    /** Response request-ID headers. */ requestIDHeaders?: string[];
+    /** Receipt metadata headers. */ rateLimitHeaders?: string[];
+    /** No-byte timeout in milliseconds. */ stallTimeoutMs?: number;
+    /** First matching model override wins. */ modelRules?: ModelRule[];
+}
+/** Validate a profile and return a provider-neutral textgen wire format. */
+declare function newWireFormat(profile: Profile): WireFormat;
+
+export { type InstructionsRole, type MaxTokensField, type ModelRule, type Profile, type StreamingPolicy, newWireFormat };