@qilin-agent/kylin 0.0.0-stage → 4.0.3

package/src/index.ts

@@ -0,0 +1,16 @@
+/** Core context type and root context implementation. */
+export * from './context.ts'
+/** Event bus, dispatch modes, and event augmentation types. */
+export * from './events.ts'
+/** Plugin fiber lifecycle, effects, and config validation helpers. */
+export * from './fiber.ts'
+/** Logger facade, logger service, message, exporter, and formatting types. */
+export * from './logger.ts'
+/** Plugin registry, dependency injection, and plugin entrypoint types. */
+export * from './registry.ts'
+/** Base service class and service lifecycle symbols. */
+export * from './service.ts'
+/** Shared internal helpers used by context, services, and plugin fibers. */
+export * from './utils.ts'
+/** Readonly references returned by volatile config schemas. */
+export type { Volatile, VolatileSnapshot } from '@qilin-agent/cosmokit'

package/src/logger.ts

@@ -0,0 +1,271 @@
+import { defineProperty, hyphenate } from '@qilin-agent/cosmokit'
+import { Context } from './context.ts'
+import { Fiber } from './fiber.ts'
+import { createCallable, joinPrototype, symbols, type Tracker } from './utils.ts'
+
+declare module './context.ts' {
+  interface Intercept {
+    logger: LoggerService.Intercept
+  }
+}
+
+/** Logger method name and severity category. */
+export type LoggerType = 'error' | 'info' | 'warn' | 'debug'
+
+/** Callable shape for one logger severity method. */
+export type LoggerMethod = (format: any, ...param: any[]) => void
+
+/** Formatter used to resolve a printf-style placeholder. */
+export type Formatter = (value: any, exporter: Exporter, message: Message) => any
+
+/** Numeric severity used when exporters decide whether to emit a message. */
+export const enum LoggerLevel {
+  ERROR = 0,
+  INFO = 1,
+  WARN = 2,
+  DEBUG = 3,
+}
+
+/** Structured log record delivered to exporters. */
+export interface Message {
+  sn: number
+  ts: number
+  name: string
+  type: LoggerType
+  level: number
+  args: any[]
+  fiber?: WeakRef<Fiber>
+}
+
+/** Sink that receives structured log messages. */
+export interface Exporter {
+  colors?: number | false
+  maxLength?: number
+  levels?: Record<string, number>
+  formatters?: Record<string, Formatter>
+  export(message: Message): void
+}
+
+/** Built-in placeholder formatters used by `Logger.format()`. */
+export const defaultFormatters: Record<string, Formatter> = {
+  s: (value) => String(value),
+  d: (value) => Math.trunc(Number(value)),
+  i: (value) => Math.trunc(Number(value)),
+  f: (value) => Number(value),
+  o: (value) => JSON.stringify(value),
+  O: (value) => JSON.stringify(value),
+  c: () => '',
+  C: (value, exporter, message) => {
+    return Logger.color(exporter, Logger.code(message.name, exporter.colors), value)
+  },
+}
+
+/** Options used when creating a named logger facade. */
+export interface LoggerOptions {
+  /** The logger name shown with each message. */
+  name: string
+  /** Message fields merged into every record from this logger. */
+  meta?: Partial<Message>
+  /** Default maximum level exported when an exporter has no own threshold. */
+  level?: number
+}
+
+/** Logger facade identity, inherited message metadata, and optional minimum level. */
+export interface Logger extends LoggerOptions {}
+/** Logger facade severity methods. */
+export interface Logger extends Record<LoggerType, LoggerMethod> {}
+
+function isAggregateError(error: any): error is Error & { errors: Error[] } {
+  return error instanceof Error && Array.isArray(error['errors'])
+}
+
+/** Logger facade for one named subsystem. */
+export class Logger {
+  static color(exporter: Exporter, code: number, value: any, decoration = '') {
+    if (!exporter.colors) return '' + value
+    return `\u001b[3${code < 8 ? code : '8;5;' + code}${exporter.colors >= 2 ? decoration : ''}m${value}\u001b[0m`
+  }
+
+  static code(name: string, level?: false | number) {
+    let hash = 0
+    for (let i = 0; i < name.length; i++) {
+      hash = ((hash << 3) - hash) + name.charCodeAt(i) + 13
+      hash |= 0
+    }
+    const colors = !level ? [] : level >= 2 ? c256 : c16
+    return colors[Math.abs(hash) % colors.length]
+  }
+
+  static format(exporter: Exporter, message: Message): string {
+    const args = message.args.slice()
+    if (args[0] instanceof Error) {
+      args[0] = args[0].stack || args[0].message
+      args.unshift('%s')
+    } else if (typeof args[0] !== 'string') {
+      args.unshift('%o')
+    }
+
+    let format: string = args.shift()
+    format = format.replace(/%([a-zA-Z%])/g, (match, char) => {
+      if (match === '%%') return '%'
+      const formatter = exporter.formatters?.[char] ?? defaultFormatters[char]
+      if (typeof formatter === 'function') {
+        const value = args.shift()
+        return formatter(value, exporter, message)
+      }
+      return match
+    })
+
+    const oFormatter = exporter.formatters?.o ?? defaultFormatters.o
+    for (let arg of args) {
+      if (typeof arg === 'object' && arg) {
+        arg = oFormatter(arg, exporter, message)
+      }
+      format += ' ' + arg
+    }
+
+    const { maxLength = 10240 } = exporter
+    return format.split(/\r?\n/g).map(line => {
+      return line.slice(0, maxLength) + (line.length > maxLength ? '...' : '')
+    }).join('\n')
+  }
+
+  constructor(options: LoggerOptions, private service: LoggerService) {
+    Object.assign(this, options)
+    this.error = this._method('error', LoggerLevel.ERROR)
+    this.info = this._method('info', LoggerLevel.INFO)
+    this.warn = this._method('warn', LoggerLevel.WARN)
+    this.debug = this._method('debug', LoggerLevel.DEBUG)
+  }
+
+  private _method(type: LoggerType, level: number): LoggerMethod {
+    return (...args: any[]) => {
+      if (args.length === 1 && args[0] instanceof Error) {
+        if (args[0].cause) {
+          this[type](args[0].cause)
+        } else if (isAggregateError(args[0])) {
+          args[0].errors.forEach(error => this[type](error))
+          return
+        }
+      }
+
+      const sn = ++this.service._snMessage
+      const ts = Date.now()
+      for (const exporter of this.service.exporters.values()) {
+        const targetLevel = exporter.levels?.[this.name] ?? exporter.levels?.default ?? this.level ?? LoggerLevel.INFO
+        if (targetLevel < level) continue
+        const message: Message = { sn, ts, type, level, name: this.name, ...this.meta, args }
+        exporter.export(message)
+      }
+    }
+  }
+}
+
+/** ANSI 16-color palette indexes used for logger name coloring. */
+export const c16 = [6, 2, 3, 4, 5, 1]
+/** ANSI 256-color palette indexes used for logger name coloring. */
+export const c256 = [
+  20, 21, 26, 27, 32, 33, 38, 39, 40, 41, 42, 43, 44, 45, 56, 57, 62,
+  63, 68, 69, 74, 75, 76, 77, 78, 79, 80, 81, 92, 93, 98, 99, 112, 113,
+  129, 134, 135, 148, 149, 160, 161, 162, 163, 164, 165, 166, 167, 168,
+  169, 170, 171, 172, 173, 178, 179, 184, 185, 196, 197, 198, 199, 200,
+  201, 202, 203, 204, 205, 206, 207, 208, 209, 214, 215, 220, 221,
+]
+
+/** Logger service configuration merged from context intercepts. */
+export namespace LoggerService {
+  export interface Intercept {
+    name?: string
+    level?: number
+  }
+}
+
+/** Callable `ctx.logger` service shape. */
+export interface LoggerService extends Record<LoggerType, LoggerMethod> {
+  (name?: string): Logger
+}
+
+/**
+ * Built-in logging service.
+ *
+ * Call `ctx.logger()` to create a named logger, or call `ctx.logger.info()`
+ * directly to log with the current fiber-derived name.
+ */
+export class LoggerService {
+  bufferSize = 1000
+  buffer: Message[] = []
+  ctx!: Context
+
+  _snMessage = 0
+  _snExporter = 0
+  exporters = new Map<number, Exporter>()
+
+  constructor(ctx: Context) {
+    const tracker: Tracker = {
+      property: 'ctx',
+      noShadow: true,
+    }
+    const self = createCallable('logger', joinPrototype(Object.getPrototypeOf(this), Function.prototype), tracker) as unknown as LoggerService
+    Object.assign(self, this)
+    self.ctx = ctx
+    defineProperty(self, symbols.tracker, tracker)
+
+    self.exporter({
+      colors: 3,
+      export: (message) => {
+        self.buffer.push(message)
+        if (self.buffer.length > self.bufferSize) {
+          self.buffer = self.buffer.slice(-self.bufferSize)
+        }
+      },
+    })
+
+    return self
+  }
+
+  /**
+   * Register an exporter and dispose it with the current fiber.
+   *
+   * @param exporter — the sink that receives structured log messages.
+   * @returns a disposer that removes the exporter.
+   */
+  exporter(exporter: Exporter) {
+    return this.ctx.effect(() => {
+      const id = ++this._snExporter
+      this.exporters.set(id, exporter)
+      return () => this.exporters.delete(id)
+    }, 'ctx.logger.exporter()')
+  }
+
+  private _resolveConfig(): LoggerService.Intercept {
+    let intercept = this.ctx[symbols.intercept]
+    const configs: LoggerService.Intercept[] = []
+    while ('logger' in intercept) {
+      if (Object.hasOwn(intercept, 'logger')) {
+        configs.unshift(intercept['logger'])
+      }
+      intercept = Object.getPrototypeOf(intercept)
+    }
+    return Object.assign({}, ...configs)
+  }
+
+  [symbols.invoke](name?: string): Logger {
+    const config = this._resolveConfig()
+    const fiber = ((this.ctx as any)[symbols.shadow] ?? this.ctx).fiber
+    name ??= config.name
+    name ??= hyphenate(fiber.name)
+    return new Logger({
+      name,
+      level: config.level,
+      meta: { fiber: new WeakRef(fiber) },
+    }, this)
+  }
+
+  static {
+    for (const type of ['error', 'info', 'warn', 'debug'] as const) {
+      ;(LoggerService.prototype as any)[type] = function (this: LoggerService, ...args: any[]) {
+        return (this as any)()[type](...args)
+      }
+    }
+  }
+}

package/src/reflect.ts

@@ -0,0 +1,418 @@
+import { defineProperty, isNullable } from '@qilin-agent/cosmokit'
+import type { Dict } from '@qilin-agent/cosmokit'
+import { Context } from './context.ts'
+import { getTraceable, symbols, withProps } from './utils.ts'
+import { Fiber, FiberState } from './fiber.ts'
+
+declare module './context.ts' {
+  interface Context {
+    /**
+     * Read a service from the store without the inject requirement.
+     *
+     * @param name — the service name.
+     * @param strict — when `true` (default), only return implementations
+     * whose providing fiber is currently active.
+     * @returns the service value, or `undefined` when not (yet) provided.
+     */
+    get<K extends string & keyof this>(name: K, strict?: boolean): undefined | this[K]
+    /** Same as above for service names outside the typed `Context` surface. */
+    get(name: string, strict?: boolean): any
+    /**
+     * Overwrite a provided service's value.
+     *
+     * Only the fiber that provided the service may set it; setting an
+     * unprovided name throws.
+     *
+     * @param name — the service name.
+     * @param value — the new service value.
+     */
+    set<K extends string & keyof this>(name: K, value: undefined | this[K]): void
+    /** Same as above for service names outside the typed `Context` surface. */
+    set(name: string, value: any): void
+    /**
+     * Register a service implementation owned by the current fiber.
+     *
+     * The service becomes visible to dependents in the same isolation scope
+     * once the fiber is active; it is unregistered (waking dependents) when
+     * the returned disposer runs or the fiber unloads. Throws if the name is
+     * already provided in this scope or declared as an accessor.
+     *
+     * @param name — the service name.
+     * @param value — the service value.
+     * @returns a disposer that unregisters the service.
+     */
+    provide<K extends string & keyof this>(name: K, value: undefined | this[K]): () => void
+    /** Same as above for service names outside the typed `Context` surface. */
+    provide(name: string, value?: any): () => void
+    /**
+     * Define a computed context property backed by get/set hooks.
+     *
+     * The accessor is removed when the current fiber unloads. Throws if the
+     * name is already declared.
+     *
+     * @param name — the context property name.
+     * @param options — the `get` hook and optional `set` hook.
+     */
+    accessor(name: string, options: Omit<Property.Accessor, 'type'>): void
+    /**
+     * Expose selected members of a service directly on `ctx`.
+     *
+     * Each mixed-in key becomes an accessor that forwards to the service
+     * (binding methods to it), so e.g. `ctx.on` forwards to `ctx.events.on`.
+     * Mixins are removed when the current fiber unloads.
+     *
+     * @param name — the context property holding the source service.
+     * @param mixins — keys to forward, or a source-key → ctx-key map.
+     */
+    mixin<K extends string & keyof this>(name: K, mixins: (keyof this & keyof this[K])[] | Dict<string>): void
+    /** Same as above with a source object instead of a context property name. */
+    mixin<T extends {}>(source: T, mixins: (keyof this & keyof T)[] | Dict<string>): void
+  }
+}
+
+function enhanceError(error: Error) {
+  const lines = error.stack!.split('\n')
+  lines.splice(0, 2, `Error: ${error.message}`)
+  error.stack = lines.join('\n')
+  return error
+}
+
+const RESERVED_WORDS = ['prototype', 'then']
+
+// - is a symbol
+// - is a reserved word (prototype, then)
+// - is a number string (0, 1, 2, ...)
+// - starts with `_`
+function isSpecialProperty(prop: string | symbol): prop is symbol {
+  return typeof prop === 'symbol'
+    || RESERVED_WORDS.includes(prop)
+    || parseInt(prop).toString() === prop
+    || prop.startsWith('_')
+}
+
+/** Context property definition known by the reflection service. */
+export type Property = Property.Service | Property.Accessor
+
+/** Property definition variants understood by `ReflectService`. */
+export namespace Property {
+  /** Service property backed by a provided implementation. */
+  export interface Service {
+    /** Discriminator. */
+    type: 'service'
+  }
+
+  /** Computed context property backed by custom get/set hooks. */
+  export interface Accessor {
+    /** Discriminator. */
+    type: 'accessor'
+    /** Compute the property value; `error` carries the caller stack for diagnostics. */
+    get: (this: Context, receiver: any, error: Error) => any
+    /** Optional setter; return `false` to reject the write. */
+    set?: (this: Context, value: any, receiver: any, error: Error) => boolean
+  }
+}
+
+/** Concrete service implementation record stored in the root reflect service. */
+export interface Impl {
+  /** The service name. */
+  name: string
+  /** The fiber that provided the service (owns its lifetime). */
+  fiber: Fiber
+  /** The current service value. */
+  value?: any
+  /** Optional availability predicate consulted before dependents may load. */
+  check?: () => boolean
+}
+
+/**
+ * Reflection and service-resolution layer installed as `ctx.reflect`.
+ *
+ * This service powers the context proxy, service registration, accessors, and
+ * the mixins that expose core service methods directly on `ctx`.
+ */
+export class ReflectService {
+  /** Proxy traps implementing service resolution for every context object. */
+  static handler: ProxyHandler<Context> = {
+    get: (target, prop, ctx: Context) => {
+      if (isSpecialProperty(prop)) {
+        return Reflect.get(target, prop, ctx)
+      }
+      if (Reflect.has(target, prop)) {
+        return getTraceable(ctx, Reflect.get(target, prop, ctx))
+      }
+
+      const error = new Error(`cannot get property "${prop}" without inject`)
+
+      try {
+        const def = target.reflect.props[prop]
+        if (def?.type === 'accessor') {
+          return def.get.call(ctx, ctx[symbols.receiver], error)
+        }
+
+        if (!ctx.fiber.runtime) return ctx.reflect.get(prop, false)
+        return ctx.events.waterfall('internal/get', ctx, prop, error, () => {
+          const key = target[symbols.isolate][prop]
+          let fiber = (ctx[symbols.shadow] as Context ?? ctx).fiber
+          while (true) {
+            const impl = fiber.store?.[prop]
+            if (impl) return getTraceable(ctx, impl.value)
+            if (prop in fiber.inject) {
+              error.message = `cannot get required service "${prop}" in inactive context`
+              throw error
+            }
+            if (!fiber.runtime) throw error
+            if (fiber.parent[symbols.isolate][prop] !== key) throw error
+            fiber = fiber.parent.fiber
+          }
+        })
+      } catch (e: any) {
+        throw e === error ? enhanceError(e) : e
+      }
+    },
+
+    set: (target, prop, value, ctx: Context) => {
+      if (isSpecialProperty(prop)) {
+        return Reflect.set(target, prop, value, ctx)
+      }
+
+      const error = new Error(`cannot set property "${prop}" without provide`)
+      const def = target.reflect.props[prop]
+      if (!def) {
+        if (!ctx.fiber.runtime) return Reflect.set(target, prop, value, ctx)
+        throw enhanceError(error)
+      }
+
+      try {
+        if (def.type === 'accessor') {
+          if (!def.set) return false
+          return def.set.call(ctx, value, ctx[symbols.receiver], error)
+        }
+
+        return ctx.events.waterfall('internal/set', ctx, prop, value, error, () => {
+          return ctx.reflect.set(prop, value, error)
+        })
+      } catch (e: any) {
+        throw e === error ? enhanceError(e) : e
+      }
+    },
+
+    has: (target, prop) => {
+      if (isSpecialProperty(prop)) {
+        return Reflect.has(target, prop)
+      }
+      if (Reflect.has(target, prop)) return true
+      return !!target.reflect.props[prop]
+    },
+  }
+
+  /** Service implementations, keyed by isolation label. */
+  public store: Dict<Impl, symbol> = Object.create(null)
+  /** Declared context properties (services and accessors), by name. */
+  public props: Dict<Property> = Object.create(null)
+
+  constructor(public ctx: Context) {
+    defineProperty(this, symbols.tracker, {
+      property: 'ctx',
+      noShadow: true,
+    })
+
+    this.mixin('reflect', ['get', 'set', 'provide', 'accessor', 'mixin'])
+    this.mixin('fiber', ['runtime', 'effect'])
+    this.mixin('registry', ['inject', 'plugin'])
+    this.mixin('events', ['on', 'once', 'parallel', 'emit', 'serial', 'bail', 'waterfall'])
+  }
+
+  /**
+   * Read a service from the store without the inject requirement.
+   *
+   * @param name — the service name.
+   * @param strict — when `true`, only return implementations whose providing
+   * fiber is currently active.
+   * @returns the service value, or `undefined` when not (yet) provided.
+   */
+  get(name: string, strict = true) {
+    return getTraceable(this.ctx, this._getImpl(name, strict)?.value)
+  }
+
+  _getImpl(name: string, strict = true) {
+    const key = this.ctx[symbols.isolate][name]
+    const impl = key && this.store[key]
+    if (!impl) return
+    if (strict && impl.fiber.state !== FiberState.ACTIVE) return
+    return impl
+  }
+
+  /**
+   * Overwrite a provided service's value.
+   *
+   * @param name — the service name.
+   * @param value — the new service value.
+   * @param error — carrier for the caller stack in diagnostics.
+   * @returns `true` on success.
+   * @throws when `name` was never provided, or was provided by another fiber.
+   */
+  set(name: string, value: any, error?: Error) {
+    const key = this.ctx[symbols.isolate][name]
+    const impl = this.store[key]
+    if (!impl) {
+      throw new Error(`cannot set property "${name}" without provide`)
+    }
+    if (impl.fiber !== this.ctx.fiber) {
+      throw new Error(`cannot set property "${name}" in multiple fibers`)
+    }
+    impl.value = value
+    return true
+  }
+
+  /**
+   * Register a service implementation owned by the current fiber.
+   *
+   * See the `ctx.provide()` overload above for the full contract.
+   *
+   * @param name — the service name.
+   * @param value — the service value.
+   * @param check — optional availability predicate for dependents.
+   * @returns a disposer that unregisters the service.
+   */
+  provide(name: string, value?: any, check?: () => boolean) {
+    return this.ctx.fiber.effect(() => {
+      if (!this.props[name]) {
+        this.props[name] ??= { type: 'service' }
+      } else if (this.props[name].type !== 'service') {
+        throw new Error(`property "${name}" is already declared as ${this.props[name].type}`)
+      }
+      this.props[name] = { type: 'service' }
+
+      this.ctx.root[symbols.isolate][name] ??= Symbol(name)
+      const key = this.ctx[symbols.isolate][name]
+      const impl: Impl = { name, value, fiber: this.ctx.fiber, check }
+      if (this.store[key]) {
+        throw new Error(`service "${name}" has been registered at <${this.store[key].fiber.name}>`)
+      }
+      this.store[key] = impl
+      this.ctx.fiber.store![name] = impl
+      if (this.ctx.fiber.state === FiberState.ACTIVE) {
+        this.notify([name])
+      }
+      return async () => {
+        delete this.store[key]
+        const fibers = this.notify([name])
+        await Promise.allSettled(fibers.map(fiber => fiber.await()))
+        // ensure self access before dependencies cleanup
+        delete this.ctx.fiber.store![name]
+      }
+    }, `ctx.provide(${JSON.stringify(name)})`)
+  }
+
+  /**
+   * Re-evaluate every fiber that requires one of the given services.
+   *
+   * @param names — the service names that changed.
+   * @param filter — restricts notification to matching isolation scopes.
+   * @returns the fibers whose dependency state was refreshed.
+   */
+  notify(names: string[], filter = (ctx: Context, name: string) => ctx[symbols.isolate][name] === this.ctx[symbols.isolate][name]) {
+    const fibers: Fiber[] = []
+    for (const runtime of this.ctx.registry.values()) {
+      for (const fiber of runtime.fibers) {
+        let hasUpdate = false
+        for (const name of names) {
+          if (!(name in fiber.inject)) continue
+          if (!filter(fiber.ctx, name)) continue
+          hasUpdate = true
+          fiber._checkImpl(name)
+        }
+        if (!hasUpdate) continue
+        fiber._refresh()
+        fibers.push(fiber)
+      }
+    }
+    for (const name of names) {
+      const self: Context = Object.create(this.ctx)
+      self[symbols.filter] = (target: Context) => filter(target, name)
+      this.ctx.events.emit(self, 'internal/service', name, this._getImpl(name, false)?.value)
+    }
+    return fibers
+  }
+
+  /**
+   * Define a computed context property backed by get/set hooks.
+   *
+   * @param name — the context property name.
+   * @param options — the `get` hook and optional `set` hook.
+   * @returns a disposer that removes the accessor.
+   */
+  accessor(name: string, options: Omit<Property.Accessor, 'type'>) {
+    return this.ctx.fiber.effect(() => {
+      if (name in this.props) {
+        throw new Error(`property "${name}" is already declared as ${this.props[name].type}`)
+      }
+      this.props[name] = { type: 'accessor', ...options }
+      return () => delete this.props[name]
+    }, `ctx.accessor(${JSON.stringify(name)})`)
+  }
+
+  /**
+   * Expose selected members of a service directly on `ctx`.
+   *
+   * See the `ctx.mixin()` overload above for the full contract.
+   *
+   * @param source — a context property name or a source object.
+   * @param mixins — keys to forward, or a source-key → ctx-key map.
+   * @returns a disposer that removes all created accessors.
+   */
+  mixin(source: any, mixins: string[] | Dict<string>) {
+    const self = this
+    return this.ctx.fiber.effect(function* () {
+      const entries = Array.isArray(mixins) ? mixins.map(key => [key, key]) : Object.entries(mixins)
+      const getTarget = (ctx: Context, error: Error) => {
+        // TODO enhance error message
+        return ctx[source]
+      }
+      for (const [key, value] of entries) {
+        yield self.accessor(value, {
+          get(receiver, error) {
+            const service = getTarget(this, error)
+            if (isNullable(service)) return service
+            const mixin = receiver ? withProps(receiver, service) : service
+            const value = Reflect.get(service, key, mixin)
+            if (typeof value !== 'function') return value
+            return value.bind(mixin ?? service)
+          },
+          set(value, receiver, error) {
+            const service = getTarget(this, error)
+            const mixin = receiver ? withProps(receiver, service) : service
+            return Reflect.set(service, key, value, mixin)
+          },
+        })
+      }
+    }, `ctx.mixin(${JSON.stringify(source)})`)
+  }
+
+  /**
+   * Attach this context's tracing wrapper to a value.
+   *
+   * @param value — the value to wrap.
+   * @returns the traceable wrapper (or the value itself when not applicable).
+   */
+  trace<T>(value: T) {
+    return getTraceable(this.ctx, value)
+  }
+
+  /**
+   * Wrap a callback so calls trace `this` and arguments to this context.
+   *
+   * @param callback — the function to wrap.
+   * @returns a proxy delegating to `callback` with traced values.
+   */
+  bind<T extends Function>(callback: T) {
+    return new Proxy(callback, {
+      apply: (target, thisArg, args) => {
+        return Reflect.apply(target, this.trace(thisArg), args.map(arg => this.trace(arg)))
+      },
+      construct: (target, args, newTarget) => {
+        return Reflect.construct(target, args.map(arg => this.trace(arg)), newTarget)
+      },
+    })
+  }
+}