abxbus 2.5.4 → 2.5.9

package/src/jsonschema.ts

@@ -0,0 +1,146 @@
+import { z } from 'zod'
+
+export type JsonSchema = boolean | z.core.JSONSchema.JSONSchema
+type JsonSchemaObject = z.core.JSONSchema.JSONSchema
+
+const isJsonSchemaObject = (value: unknown): value is JsonSchemaObject => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export const isJsonSchema = (value: unknown): value is JsonSchema => {
+  if (typeof value === 'boolean') {
+    return true
+  }
+  if (!isJsonSchemaObject(value)) {
+    return false
+  }
+  if ('_zod' in value || '_def' in value || '~standard' in value) {
+    return false
+  }
+  return true
+}
+
+const nullUnionCandidates = (schema: Record<string, unknown>): Record<string, unknown>[] | null => {
+  if (Array.isArray(schema.type) && schema.type.includes('null')) {
+    const non_null_types = schema.type.filter((item): item is string => typeof item === 'string' && item !== 'null')
+    if (non_null_types.length > 0) {
+      return [{ type: non_null_types.length === 1 ? non_null_types[0] : non_null_types }, { type: 'null' }]
+    }
+  }
+
+  return null
+}
+
+export const normalizeJsonSchema = (schema: JsonSchema): JsonSchema => {
+  const normalized = normalizeJsonSchemaValue(schema)
+  if (!isJsonSchemaObject(normalized)) {
+    return normalized as JsonSchema
+  }
+  const schema_record = { ...normalized } as JsonSchemaObject
+  const definitions = schema_record.$defs
+  const root_ref = rootRefForSchema(schema_record, definitions)
+  if (!root_ref || !definitions) {
+    schema_record.$schema ??= 'https://json-schema.org/draft/2020-12/schema'
+    return schema_record
+  }
+  const root_name = root_ref.slice('#/$defs/'.length)
+  const root_schema = definitions[root_name]
+  if (!isJsonSchemaObject(root_schema)) {
+    schema_record.$schema ??= 'https://json-schema.org/draft/2020-12/schema'
+    return schema_record
+  }
+  const rewritten_root = rewriteJsonSchemaRefs(root_schema, { [root_ref]: '#' }) as JsonSchemaObject
+  const remaining_defs = Object.fromEntries(Object.entries(definitions).filter(([name]) => name !== root_name))
+  if (Object.keys(remaining_defs).length > 0) {
+    rewritten_root.$defs = rewriteJsonSchemaRefs(remaining_defs, { [root_ref]: '#' }) as Record<string, JsonSchemaObject>
+  }
+  rewritten_root.$schema ??= schema_record.$schema ?? 'https://json-schema.org/draft/2020-12/schema'
+  setTitleFromInlinedRootDefinition(rewritten_root, root_name)
+  return rewritten_root
+}
+
+const rootRefForSchema = (schema: JsonSchemaObject, definitions: Record<string, JsonSchemaObject> | undefined): string | null => {
+  if (typeof schema.$ref === 'string' && schema.$ref.startsWith('#/$defs/')) {
+    return schema.$ref
+  }
+  if (!definitions) {
+    return null
+  }
+  const root = schemaWithoutSchemaAndDefinitions(schema)
+  for (const [name, definition] of Object.entries(definitions)) {
+    if (JSON.stringify(definition) === JSON.stringify(root)) {
+      return `#/$defs/${name}`
+    }
+  }
+  return null
+}
+
+const schemaWithoutSchemaAndDefinitions = (schema: JsonSchemaObject): Record<string, unknown> => {
+  const root: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(schema)) {
+    if (key !== '$schema' && key !== '$defs') {
+      root[key] = value
+    }
+  }
+  return root
+}
+
+const setTitleFromInlinedRootDefinition = (schema: JsonSchemaObject, root_name: string): void => {
+  if (root_name.startsWith('__schema')) return
+  schema.title ??= root_name
+}
+
+const rewriteJsonSchemaRefs = (schema: unknown, refs: Record<string, string>): unknown => {
+  if (Array.isArray(schema)) {
+    return schema.map((item) => rewriteJsonSchemaRefs(item, refs))
+  }
+  if (!isJsonSchemaObject(schema)) {
+    return schema
+  }
+  const rewritten: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(schema)) {
+    rewritten[key] = rewriteJsonSchemaRefs(value, refs)
+  }
+  if (typeof rewritten.$ref === 'string' && rewritten.$ref in refs) {
+    rewritten.$ref = refs[rewritten.$ref]
+  }
+  return rewritten
+}
+
+const normalizeJsonSchemaValue = (schema: unknown): unknown => {
+  if (Array.isArray(schema)) {
+    return schema.map((item) => normalizeJsonSchemaValue(item))
+  }
+  if (!isJsonSchemaObject(schema)) {
+    return schema
+  }
+
+  const normalized: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(schema)) {
+    normalized[key] = normalizeJsonSchemaValue(value)
+  }
+  if (Array.isArray(normalized.required) && normalized.required.every((item) => typeof item === 'string')) {
+    normalized.required = [...normalized.required].sort()
+  }
+
+  const null_union_candidates = nullUnionCandidates(normalized)
+  if (null_union_candidates !== null) {
+    const merged: Record<string, unknown> = { anyOf: normalizeJsonSchemaValue(null_union_candidates) }
+    for (const [key, value] of Object.entries(normalized)) {
+      if (key !== 'type') {
+        merged[key] = value
+      }
+    }
+    return merged
+  }
+
+  return normalized
+}
+
+export const toJsonSchema = (schema: z.core.$ZodType): JsonSchema => {
+  return normalizeJsonSchema(z.toJSONSchema(schema) as JsonSchema)
+}
+
+export const fromJsonSchema = (schema: JsonSchema): z.ZodTypeAny => {
+  return z.fromJSONSchema(schema)
+}

package/src/retry.ts

@@ -21,6 +21,8 @@ type RetryDecorator = {
 
 const MULTIPROCESS_SEMAPHORE_DIRNAME = 'browser_use_semaphores'
 const MULTIPROCESS_STALE_LOCK_MS = 5 * 60 * 1000
+const RETRY_SLOW_WARNING_THROTTLE_MS = 2000
+const RETRY_SLOW_WARNING_ARGS_MAX_LENGTH = 80
 
 let multiprocess_fallback_reason_logged: string | null = null
 
@@ -44,6 +46,9 @@ export interface RetryOptions {
   /** Per-attempt timeout in seconds. Default: undefined (no per-attempt timeout) */
   timeout?: number | null
 
+  /** Emit a warning when a decorated call exceeds this many seconds. Default: undefined (disabled) */
+  slow_timeout?: number | null
+
   /** Maximum concurrent executions sharing this semaphore. Default: undefined (no concurrency limit) */
   semaphore_limit?: number | null
 
@@ -238,6 +243,7 @@ export function retry(options: RetryOptions = {}): RetryDecorator {
     retry_backoff_factor = 1.0,
     retry_on_errors,
     timeout,
+    slow_timeout,
     semaphore_limit,
     semaphore_name: semaphore_name_option,
     semaphore_lax = true,
@@ -245,10 +251,13 @@ export function retry(options: RetryOptions = {}): RetryDecorator {
     semaphore_timeout,
   } = options
 
-  const decorateFunction = <T extends AnyFunction>(target: T, _context?: ClassMethodDecoratorContext): T => {
-    const fn_name = target.name || (_context?.name as string) || 'anonymous'
+  const decorateFunction = <T extends AnyFunction>(target: T, _context?: ClassMethodDecoratorContext, owner_name?: string | null): T => {
+    const base_fn_name = target.name || (_context?.name as string) || 'anonymous'
+    let fn_name = owner_name ? `${owner_name}.${base_fn_name}` : base_fn_name
     const effective_max_attempts = Math.max(1, max_attempts)
     const effective_retry_after = Math.max(0, retry_after)
+    const effective_slow_timeout_ms = slow_timeout != null && slow_timeout > 0 ? slow_timeout * 1000 : null
+    let last_slow_warning_at = 0
 
     const shouldRetry = (error: unknown): boolean => {
       if (!retry_on_errors || retry_on_errors.length === 0) return true
@@ -275,6 +284,14 @@ export function retry(options: RetryOptions = {}): RetryDecorator {
       }
     }
 
+    const emitSlowWarningIfDue = (args: any[], start_time: number): void => {
+      if (effective_slow_timeout_ms == null) return
+      const now = Date.now()
+      if (now - last_slow_warning_at < RETRY_SLOW_WARNING_THROTTLE_MS) return
+      last_slow_warning_at = now
+      console.warn(`Warning: ${fn_name}(${formatRetrySlowWarningArgs(args)}) slow (${((now - start_time) / 1000).toFixed(1)}s)`)
+    }
+
     const runRetryLoopFromThenable = async (
       this_arg: any,
       args: any[],
@@ -373,26 +390,45 @@ export function retry(options: RetryOptions = {}): RetryDecorator {
 
       // ── Retry loop (runs inside the semaphore and re-entrancy context) ──
       const runRetryLoop = async (): Promise<any> => {
-        for (let attempt = 1; attempt <= effective_max_attempts; attempt++) {
-          try {
-            if (timeout != null && timeout > 0) {
-              return await _runWithTimeout(() => Promise.resolve(target.apply(this, args)), timeout * 1000, attempt)
-            } else {
-              return await Promise.resolve(target.apply(this, args))
-            }
-          } catch (error) {
-            if (!shouldRetry(error)) throw error
+        const call_started_at = Date.now()
+        const warning_args = [...args]
+        const slow_warning_timer =
+          effective_slow_timeout_ms == null
+            ? null
+            : setTimeout(() => emitSlowWarningIfDue(warning_args, call_started_at), effective_slow_timeout_ms)
+        const finishSlowWarning = (): void => {
+          if (slow_warning_timer !== null) {
+            clearTimeout(slow_warning_timer)
+          }
+          if (effective_slow_timeout_ms != null && Date.now() - call_started_at >= effective_slow_timeout_ms) {
+            emitSlowWarningIfDue(warning_args, call_started_at)
+          }
+        }
 
-            // Last attempt: rethrow
-            if (attempt >= effective_max_attempts) throw error
+        try {
+          for (let attempt = 1; attempt <= effective_max_attempts; attempt++) {
+            try {
+              if (timeout != null && timeout > 0) {
+                return await _runWithTimeout(() => Promise.resolve(target.apply(this, args)), timeout * 1000, attempt)
+              } else {
+                return await Promise.resolve(target.apply(this, args))
+              }
+            } catch (error) {
+              if (!shouldRetry(error)) throw error
+
+              // Last attempt: rethrow
+              if (attempt >= effective_max_attempts) throw error
 
-            // Wait before next attempt with exponential backoff
-            await asyncRetryDelay(attempt)
+              // Wait before next attempt with exponential backoff
+              await asyncRetryDelay(attempt)
+            }
           }
-        }
 
-        // Unreachable, but satisfies the type checker
-        throw new Error(`retry(${fn_name}): unexpected end of retry loop`)
+          // Unreachable, but satisfies the type checker
+          throw new Error(`retry(${fn_name}): unexpected end of retry loop`)
+        } finally {
+          finishSlowWarning()
+        }
       }
 
       try {
@@ -452,27 +488,52 @@ export function retry(options: RetryOptions = {}): RetryDecorator {
       }
 
       const runRetryLoop = (): any => {
-        for (let attempt = 1; attempt <= effective_max_attempts; attempt++) {
-          const attempt_started_at = Date.now()
-          try {
-            const result = target.apply(this, args)
-            if (isThenable(result)) {
-              return runRetryLoopFromThenable(this, args, result, attempt)
-            }
-            if (timeout != null && timeout > 0 && Date.now() - attempt_started_at > timeout * 1000) {
-              throw new RetryTimeoutError(`Timed out after ${timeout}s (attempt ${attempt})`, {
-                timeout_seconds: timeout,
-                attempt,
-              })
+        const call_started_at = Date.now()
+        const warning_args = [...args]
+        const slow_warning_timer =
+          effective_slow_timeout_ms == null
+            ? null
+            : setTimeout(() => emitSlowWarningIfDue(warning_args, call_started_at), effective_slow_timeout_ms)
+        const finishSlowWarning = (): void => {
+          if (slow_warning_timer !== null) {
+            clearTimeout(slow_warning_timer)
+          }
+          if (effective_slow_timeout_ms != null && Date.now() - call_started_at >= effective_slow_timeout_ms) {
+            emitSlowWarningIfDue(warning_args, call_started_at)
+          }
+        }
+
+        let finish_on_return = true
+        try {
+          for (let attempt = 1; attempt <= effective_max_attempts; attempt++) {
+            const attempt_started_at = Date.now()
+            try {
+              const result = target.apply(this, args)
+              if (isThenable(result)) {
+                finish_on_return = false
+                return runRetryLoopFromThenable(this, args, result, attempt).finally(finishSlowWarning)
+              }
+              if (timeout != null && timeout > 0 && Date.now() - attempt_started_at > timeout * 1000) {
+                throw new RetryTimeoutError(`Timed out after ${timeout}s (attempt ${attempt})`, {
+                  timeout_seconds: timeout,
+                  attempt,
+                })
+              }
+              return result
+            } catch (error) {
+              if (!shouldRetry(error)) throw error
+              if (attempt >= effective_max_attempts) {
+                throw error
+              }
+              syncRetryDelay(attempt)
             }
-            return result
-          } catch (error) {
-            if (!shouldRetry(error)) throw error
-            if (attempt >= effective_max_attempts) throw error
-            syncRetryDelay(attempt)
+          }
+          throw new Error(`retry(${fn_name}): unexpected end of retry loop`)
+        } finally {
+          if (finish_on_return) {
+            finishSlowWarning()
           }
         }
-        throw new Error(`retry(${fn_name}): unexpected end of retry loop`)
       }
 
       try {
@@ -494,7 +555,8 @@ export function retry(options: RetryOptions = {}): RetryDecorator {
       _context.addInitializer(function (this: unknown) {
         const owner_name = findDecoratedMethodOwnerName(this, _context, retryWrapper)
         if (owner_name) {
-          Object.defineProperty(retryWrapper, 'name', { value: `${owner_name}.${fn_name}`, configurable: true })
+          fn_name = `${owner_name}.${target.name || (_context.name as string) || 'anonymous'}`
+          Object.defineProperty(retryWrapper, 'name', { value: fn_name, configurable: true })
         }
       })
     }
@@ -507,7 +569,13 @@ export function retry(options: RetryOptions = {}): RetryDecorator {
     descriptor?: LegacyMethodDescriptor
   ): T | LegacyMethodDescriptor {
     if (descriptor?.value && typeof descriptor.value === 'function') {
-      descriptor.value = decorateFunction(descriptor.value)
+      const owner_name =
+        target && (typeof target === 'object' || typeof target === 'function')
+          ? typeof target === 'function'
+            ? target.name
+            : (target as { constructor?: { name?: string } }).constructor?.name
+          : null
+      descriptor.value = decorateFunction(descriptor.value, undefined, owner_name)
       return descriptor
     }
     if (typeof target === 'function') {
@@ -569,6 +637,32 @@ function isThenable(value: unknown): value is PromiseLike<unknown> {
   )
 }
 
+function formatRetrySlowWarningArgs(args: any[]): string {
+  const preview = args.map(formatRetrySlowWarningValue).join(', ')
+  if (preview.length > RETRY_SLOW_WARNING_ARGS_MAX_LENGTH) {
+    return `${preview.slice(0, RETRY_SLOW_WARNING_ARGS_MAX_LENGTH - 3).replace(/,?\s*$/, '')}...`
+  }
+  return preview
+}
+
+function formatRetrySlowWarningValue(value: unknown): string {
+  let text: string
+  if (typeof value === 'string') {
+    text = value
+  } else if (value === null || value === undefined) {
+    text = String(value)
+  } else if (typeof value === 'object') {
+    try {
+      text = JSON.stringify(value)
+    } catch {
+      text = String(value)
+    }
+  } else {
+    text = String(value)
+  }
+  return text.replace(/['"]/g, '').slice(0, 3)
+}
+
 /**
  * Try to acquire a semaphore within a timeout. Returns true if acquired, false if timed out.
  * If the semaphore is acquired after the timeout (due to the waiter remaining queued),

package/src/types.ts

@@ -1,11 +1,11 @@
 import { z } from 'zod'
-import type { BaseEvent } from './BaseEvent.js'
+import type { BaseEvent, EventClass as BaseEventClass } from './BaseEvent.js'
+import { fromJsonSchema, isJsonSchema, type JsonSchema } from './jsonschema.js'
 
 export type EventStatus = 'pending' | 'started' | 'completed'
+export type { EventClass } from './BaseEvent.js'
 
-export type EventClass<T extends BaseEvent = BaseEvent> = { event_type?: string } & (new (...args: any[]) => T)
-
-export type EventPattern<T extends BaseEvent = BaseEvent> = string | EventClass<T>
+export type EventPattern<T extends BaseEvent = BaseEvent> = string | BaseEventClass<T>
 
 export type EventWithResultSchema<TResult> = BaseEvent & { __event_result_type__?: TResult }
 
@@ -13,7 +13,7 @@ export type EventResultType<TEvent extends BaseEvent> = TEvent extends { __event
 
 export type EventResultTypeConstructor = StringConstructor | NumberConstructor | BooleanConstructor | ArrayConstructor | ObjectConstructor
 
-export type EventResultTypeInput = z.ZodTypeAny | EventResultTypeConstructor | unknown
+export type EventResultTypeInput = z.ZodTypeAny | EventResultTypeConstructor | JsonSchema
 
 export type EventHandlerReturn<T extends BaseEvent = BaseEvent> = EventResultType<T> | BaseEvent | null | void
 
@@ -74,7 +74,7 @@ export const normalizeEventPattern = (event_pattern: EventPattern | '*'): string
   } catch {
     preview = String(event_pattern).slice(0, 30)
   }
-  throw new Error('bus.on(match_pattern, ...) must be a string event type, "*", or a BaseEvent class, got: ' + preview)
+  throw new Error('bus.on(match_pattern, ...) must be a string event type, "*", or a BaseEvent.extend() event class, got: ' + preview)
 }
 
 export const isZodSchema = (value: unknown): value is z.ZodTypeAny => !!value && typeof (value as z.ZodTypeAny).safeParse === 'function'
@@ -107,19 +107,7 @@ export const extractZodShape = (raw: Record<string, unknown>): z.ZodRawShape =>
   return shape as z.ZodRawShape
 }
 
-export const toJsonSchema = (schema: unknown): unknown => {
-  if (!schema || !isZodSchema(schema)) return schema
-  const zod_any = z as unknown as { toJSONSchema: (input: z.ZodTypeAny) => unknown }
-  // Cross-language roundtrips preserve core structural types; constraint keywords may not roundtrip exactly.
-  return zod_any.toJSONSchema(schema)
-}
-
-export const fromJsonSchema = (schema: unknown): z.ZodTypeAny => {
-  const zod_any = z as unknown as { fromJSONSchema: (input: unknown) => z.ZodTypeAny }
-  return zod_any.fromJSONSchema(schema)
-}
-
-export const normalizeEventResultType = (value: EventResultTypeInput): z.ZodTypeAny | undefined => {
+export function normalizeEventResultType(value: unknown): z.ZodTypeAny | undefined {
   if (value === undefined || value === null) {
     return undefined
   }
@@ -130,5 +118,8 @@ export const normalizeEventResultType = (value: EventResultTypeInput): z.ZodType
   if (constructor_schema) {
     return constructor_schema
   }
+  if (!isJsonSchema(value)) {
+    throw new Error(`event_result_type must be a Zod schema, constructor shorthand, or JSON Schema value, got: ${typeof value}`)
+  }
   return fromJsonSchema(value)
 }