cartethyia 2.7.3 → 2.7.5

package/src/transport/shutdown-notice.ts

@@ -15,9 +15,10 @@
  */
 import { GatewayError, type GatewayErrorCode } from "../protocol/gateway-error";
 
-export interface ShutdownNotice {
-  readonly code: Extract<GatewayErrorCode, "shutting_down" | "restart_for_update">;
+interface ShutdownNotice {
+  readonly code: Extract<GatewayErrorCode, "shutting_down">;
   readonly message: string;
+  readonly reason?: string;
 }
 
 /**
@@ -26,13 +27,21 @@ export interface ShutdownNotice {
  * with it before swapping the image so its callers are told the process is
  * coming straight back.
  */
-export const UPDATE_SHUTDOWN_REASON = "update";
+const UPDATE_SHUTDOWN_REASON = "update";
 
 export function shutdownNotice(reason: string | undefined): ShutdownNotice {
   if (reason === UPDATE_SHUTDOWN_REASON) {
-    return { code: "restart_for_update", message: "system will be back in a minute" };
+    return {
+      code: "shutting_down",
+      message:
+        "Service is shutting down for an update; it will be back in about a minute (request {requestId}). Maintenance mode — back in a minute 🧘",
+      reason: "restart_for_update",
+    };
   }
-  return { code: "shutting_down", message: "Service is shutting down" };
+  return {
+    code: "shutting_down",
+    message: "Service is shutting down (request {requestId}). Come back shortly 🧘",
+  };
 }
 
 /**
@@ -47,7 +56,12 @@ export function shutdownNotice(reason: string | undefined): ShutdownNotice {
  */
 export function shutdownError(reason: string | undefined): GatewayError {
   const notice = shutdownNotice(reason);
-  return new GatewayError(notice.code, 503, notice.message);
+  return new GatewayError(
+    notice.code,
+    503,
+    notice.message,
+    notice.reason === undefined ? {} : { reason: notice.reason },
+  );
 }
 
 /**
@@ -62,7 +76,5 @@ export function shutdownError(reason: string | undefined): GatewayError {
  */
 export function drainAbortReason(reason: unknown): GatewayError | undefined {
   if (!(reason instanceof GatewayError)) return undefined;
-  return reason.code === "shutting_down" || reason.code === "restart_for_update"
-    ? reason
-    : undefined;
+  return reason.code === "shutting_down" ? reason : undefined;
 }

package/src/transport/surface/adapters.ts

@@ -26,7 +26,7 @@ export function eventText(event: CanonicalEvent): string | undefined {
 // The endpoint path is authoritative: user-agent sniffing and prompt-text
 // marker scanning never override it, so routing cannot depend on client
 // identity strings or prompt content.
-export type WinningSource =
+type WinningSource =
   "explicit_marker" | "body_shape" | "endpoint_path";
 
 export interface SurfaceInput {
@@ -35,7 +35,7 @@ export interface SurfaceInput {
   path: string;
 }
 
-export interface SurfaceDetection {
+interface SurfaceDetection {
   surface: SourceSurface;
   winning_source: WinningSource;
   /**
@@ -64,7 +64,7 @@ export interface SurfaceAdapter {
  * it explicitly. Both detection lookups read this table, so adding a surface
  * is one row here plus its adapter.
  */
-export interface SurfaceDescriptor {
+interface SurfaceDescriptor {
   readonly surface: SourceSurface;
   readonly pathPrefix: string;
 }

package/src/transport/surface/chat/encode.ts

@@ -37,8 +37,8 @@ import type { ChatEncodeOptions, ChunkBase, JsonObject } from "./parse";
  */
 export function repairToolArguments(raw: string): string {
   if (raw.length === 0) return "{}";
-  const repaired = repairToolArgumentText(raw);
   try {
+    const repaired = repairToolArgumentText(raw);
     const parsed: unknown = JSON.parse(repaired);
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return raw;
     return repaired;
@@ -52,7 +52,7 @@ function repairToolArgumentText(json: string): string {
   return jsonrepair(json);
 }
 
-export function bytesToString(value: string | Uint8Array): string {
+function bytesToString(value: string | Uint8Array): string {
   return typeof value === "string" ? value : new TextDecoder().decode(value);
 }
 
@@ -84,7 +84,7 @@ export function getModel(options: ChatEncodeOptions, events: CanonicalEvent[]):
  * placeholder — passing the provider's own bytes through is the whole point of
  * the extension — but never an explicit configuration.
  */
-export function resolveObfuscation(options: ChatEncodeOptions): {
+function resolveObfuscation(options: ChatEncodeOptions): {
   value: string | undefined;
   pinned: boolean;
 } {
@@ -96,7 +96,7 @@ export function resolveObfuscation(options: ChatEncodeOptions): {
   return { value: undefined, pinned: false };
 }
 
-export function eventObfuscation(event: CanonicalEvent): string | undefined {
+function eventObfuscation(event: CanonicalEvent): string | undefined {
   if (event.type !== "content_delta" || event.content.kind !== "extension") return undefined;
   if (!event.content.name.includes("obfuscat")) return undefined;
   const payload = event.content.payload;
@@ -106,13 +106,13 @@ export function eventObfuscation(event: CanonicalEvent): string | undefined {
 }
 
 /** Audio output payload carried as an `audio` extension content part. */
-export function eventAudio(event: CanonicalEvent): Record<string, unknown> | undefined {
+function eventAudio(event: CanonicalEvent): Record<string, unknown> | undefined {
   if (event.type !== "content_delta" || event.content.kind !== "extension") return undefined;
   if (event.content.name !== "audio") return undefined;
   return isRecord(event.content.payload) ? event.content.payload : undefined;
 }
 
-export function eventReasoningText(event: CanonicalEvent): string | undefined {
+function eventReasoningText(event: CanonicalEvent): string | undefined {
   if (event.type !== "content_delta" || event.content.kind !== "reasoning") return undefined;
   return reasoningTextOf(event.content);
 }
@@ -144,7 +144,7 @@ function mergedReasoningText(events: readonly CanonicalEvent[]): string {
 export function finishReason(stopReason: CanonicalStopReason | undefined): string {
   return chatFinishReason(stopReason);
 }
-export function eventToolCall(
+function eventToolCall(
   event: CanonicalEvent,
 ): { state: ToolCallState; hasArguments: boolean } | undefined {
   if (event.type === "tool_call_delta") {

package/src/transport/surface/chat/parse.ts

@@ -32,7 +32,7 @@ export interface JsonObject {
   [key: string]: unknown;
 }
 
-export interface ParsedToolCall {
+interface ParsedToolCall {
   id: string;
   name: string;
   arguments: string;
@@ -57,7 +57,7 @@ export interface ChunkBase {
 
 
 
-export function isSurfaceInput(value: unknown): value is SurfaceInput {
+function isSurfaceInput(value: unknown): value is SurfaceInput {
   return isRecord(value) && "body" in value && "path" in value && typeof value.path === "string";
 }
 
@@ -75,7 +75,7 @@ export function requestBody(input: unknown): unknown {
   return decodeBody(isSurfaceInput(input) ? input.body : input);
 }
 
-export function nonNegativeNumber(value: unknown): number | undefined {
+function nonNegativeNumber(value: unknown): number | undefined {
   const number = asNumber(value);
   return number !== undefined && number >= 0 ? number : undefined;
 }
@@ -87,13 +87,13 @@ const AUDIO_FORMAT_MEDIA_TYPE: Readonly<Record<string, string>> = {
   mpeg: "audio/mpeg",
 };
 
-export function audioFormatToMediaType(format: string | undefined): string {
+function audioFormatToMediaType(format: string | undefined): string {
   if (format === undefined || format.length === 0) return "audio/mpeg";
   if (format.includes("/")) return format;
   return AUDIO_FORMAT_MEDIA_TYPE[format.toLowerCase()] ?? "audio/mpeg";
 }
 
-export function parseContentPart(value: unknown): ContentPart {
+function parseContentPart(value: unknown): ContentPart {
   if (typeof value === "string") return textPart(value);
   if (!isRecord(value)) {
     throw new Error("Malformed content part: expected string or object");
@@ -173,7 +173,7 @@ export function parseContentPart(value: unknown): ContentPart {
   throw new Error(`Malformed content part: unsupported type "${type ?? "unknown"}"`);
 }
 
-export function parseContent(value: unknown): ContentPart[] {
+function parseContent(value: unknown): ContentPart[] {
   if (typeof value === "string") return [textPart(value)];
   if (!Array.isArray(value)) return [];
   return value.map((part) => parseContentPart(part));
@@ -271,7 +271,7 @@ export function parseMessage(value: unknown): CanonicalMessage {
 }
 
 
-export function addExtension(
+function addExtension(
   controls: GenerationControls,
   key: `extension:${string}`,
   value: unknown,

package/src/transport/surface/completion.ts

@@ -9,7 +9,7 @@ import { usageToChatWire, type OpenAiUsage } from "../../providers/provider-usag
 import { TEXT_ENCODER } from "../../protocol/sse-frame";
 import { SurfaceStreamEncoder } from "./stream-frame";
 
-export interface CompletionEncodingOptions {
+interface CompletionEncodingOptions {
   response_id?: string;
   model?: string;
   created?: number;
@@ -150,7 +150,7 @@ export class CompletionStreamEncoder extends SurfaceStreamEncoder<CanonicalEvent
   }
 }
 
-export class CompletionAdapter implements SurfaceAdapter {
+class CompletionAdapter implements SurfaceAdapter {
   readonly surface = "completion" as const;
 
   matchesBodyShape(body: unknown): boolean {
@@ -166,7 +166,7 @@ export class CompletionAdapter implements SurfaceAdapter {
       throw new GatewayError(
         "invalid_request",
         400,
-        "completion requests require a non-empty prompt",
+        "completion requests require a non-empty prompt (request {requestId}). Check the shape of what you sent — then resend 🪞",
       );
     const controls: GenerationControls = {};
     for (const field of ["temperature", "top_p", "n", "seed"] as const)

package/src/transport/surface/content-parts.ts

@@ -12,7 +12,7 @@ export function textPart(text: string): ContentPart {
  * `document.source`). Each parser reads its own shape and hands the extracted
  * values here so the data-URI split happens once.
  */
-export interface RawFileBlock {
+interface RawFileBlock {
   /** Inline payload — may be raw base64 or a whole `data:` URI. */
   readonly data?: unknown;
   readonly media_type?: string | undefined;

package/src/transport/surface/dialects.ts

@@ -6,7 +6,7 @@ import { completeRequiredSchema } from "../../protocol/codecs";
 import type { ToolDefinition } from "../../protocol/canonical-model";
 
 /** Tool-definition dialects preserve each surface's distinct wire fields. */
-export type ToolDialect = "chat" | "responses" | "messages";
+type ToolDialect = "chat" | "responses" | "messages";
 
 /**
  * Parses a tool definition from one wire dialect.
@@ -165,7 +165,7 @@ function classifyNativeToolType(type: string): Exclude<ToolDefinition["tool_type
 
 export const CANONICAL_REASONING_EFFORTS: ReadonlySet<string> = new Set(REASONING_EFFORTS);
 
-export function isReasoningEffort(value: unknown): value is NonNullable<ReasoningIntent["effort"]> {
+function isReasoningEffort(value: unknown): value is NonNullable<ReasoningIntent["effort"]> {
   return typeof value === "string" && CANONICAL_REASONING_EFFORTS.has(value as NonNullable<ReasoningIntent["effort"]>);
 }
 

package/src/transport/surface/messages/encode.ts

@@ -27,7 +27,7 @@ export function requireMessagesToolName(name: string | undefined, callId: string
   throw new GatewayError(
     "transport_unavailable",
     502,
-    "Upstream tool call is missing a tool name",
+    "Upstream tool call is missing a tool name (request {requestId}). The upstream came back empty-handed — retry 🌙",
     { callId, reason: "missing_tool_name" },
     "upstream",
   );

package/src/transport/surface/messages/parse.ts

@@ -53,7 +53,7 @@ export interface MessagesStreamEvent extends MessagesWireObject {
     | "message_stop";
 }
 
-export function contentArray(value: unknown, label: string): unknown[] {
+function contentArray(value: unknown, label: string): unknown[] {
   if (stringValue(value)) return [value];
   if (!Array.isArray(value)) throw new Error(`Messages ${label} must be a string or block array`);
   return value;
@@ -165,7 +165,7 @@ export function parseBlock(value: unknown): ContentPart {
   };
 }
 
-export function parseBlocks(value: unknown, label: string): ContentPart[] {
+function parseBlocks(value: unknown, label: string): ContentPart[] {
   return contentArray(value, label).map(parseBlock);
 }
 
@@ -207,7 +207,7 @@ export function parseTools(value: unknown): ToolDefinition[] | undefined {
 
 
 /** Reads `thinking.block_binding.prefix_mismatch_behavior` when present. */
-export function prefixMismatchBehavior(value: unknown): "drop_block" | "error" | undefined {
+function prefixMismatchBehavior(value: unknown): "drop_block" | "error" | undefined {
   if (!isRecord(value)) return undefined;
   const behavior = value["prefix_mismatch_behavior"];
   if (behavior === "drop_block" || behavior === "error") return behavior;

package/src/transport/surface/responses/adapter.ts

@@ -7,7 +7,7 @@ import { hasOwn, parseResponsesRequest, unwrapBody } from "./parse";
 import { encodeResponsesEvents, encodeResponsesWireEvents } from "./encode";
 
 /** The OpenAI Responses public surface adapter. */
-export class ResponsesAdapter implements SurfaceAdapter {
+class ResponsesAdapter implements SurfaceAdapter {
   readonly surface = "responses" as const;
 
   /** Check only top-level Responses shape markers, never arbitrary prompt text. */

package/src/transport/surface/responses/errors.ts

@@ -1,15 +1,6 @@
 import { GatewayError } from "../../../protocol/gateway-error";
 
 /** Typed failures for the OpenAI Responses surface. */
-export class ResponsesReasoningError extends GatewayError {
-  readonly field: "include" | "store" | "reasoning.encrypted_content";
-
-  constructor(field: "include" | "store" | "reasoning.encrypted_content", message: string) {
-    super("capability_unsupported", 400, message, { field });
-    this.name = "ResponsesReasoningError";
-    this.field = field;
-  }
-}
 
 /** Stable typed failure for malformed canonical sequence numbers. */
 export class ResponsesSequenceError extends GatewayError {

package/src/transport/vision-handoff-cache.ts

@@ -0,0 +1,58 @@
+/**
+ * In-process cache of vision-handoff descriptions.
+ *
+ * The key is a deterministic hash of the *set* of image payloads the handoff
+ * actually described (the last image-carrying user turn). Re-sending the same
+ * attachment — the same image in a later turn, or the same conversation
+ * replayed — skips a second vision call entirely. Bounded and TTL'd so it can
+ * never grow without limit.
+ *
+ * The cache is keyed by the active image set rather than a single image
+ * because one vision model call describes the whole set in a single block of
+ * text; you cannot reliably split that block back into per-image descriptions.
+ * A repeated single-image request still hits, as does any repeated set.
+ */
+import { createHash } from "node:crypto";
+
+const CACHE_MAX_ENTRIES = 512;
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+interface CacheEntry {
+  readonly description: string;
+  readonly at: number;
+}
+
+const store = new Map<string, CacheEntry>();
+
+/** Deterministic hash of one canonical image part's payload. */
+export function hashImagePart(part: { kind: "image"; payload: unknown }): string {
+  const payload =
+    typeof part.payload === "string" ? part.payload : JSON.stringify(part.payload);
+  return createHash("sha256").update(`image:${payload}`).digest("hex");
+}
+
+/** Look up a previously stored description for an active image set hash. */
+export function getCachedVisionDescription(hash: string): string | undefined {
+  const entry = store.get(hash);
+  if (entry === undefined) return undefined;
+  if (Date.now() - entry.at > CACHE_TTL_MS) {
+    store.delete(hash);
+    return undefined;
+  }
+  return entry.description;
+}
+
+/** Clear the vision-handoff description cache (test isolation). */
+export function clearCachedVisionDescriptions(): void {
+  store.clear();
+}
+
+/** Store the description produced for an active image set hash. */
+export function setCachedVisionDescription(hash: string, description: string): void {
+  store.set(hash, { description, at: Date.now() });
+  // Evict the oldest (first-inserted) entry when over the cap.
+  if (store.size > CACHE_MAX_ENTRIES) {
+    const oldestKey = store.keys().next().value as string | undefined;
+    if (oldestKey !== undefined) store.delete(oldestKey);
+  }
+}