@loutrejs/loutre 0.6.0 → 0.7.0

package/dist/application/kernel.d.ts

@@ -1,5 +1,5 @@
 /// <reference lib="esnext.disposable" preserve="true" />
-import type { RuntimeCapabilityBinding, TokenLike, TokenValue } from '../core/index.js';
+import type { RuntimeCapabilityBinding, RuntimeInstrumentation, TokenLike, TokenValue } from '../core/index.js';
 import { type ApplicationModelGraphIR } from '../graph/index.js';
 import { type Logger } from '../runtime/index.js';
 import type { ApplicationDefinition, ApplicationExtensionHostApis, BootstrapArguments } from './definition.js';
@@ -16,6 +16,7 @@ export type KernelApplicationOptions<TDefinition extends ApplicationDefinition>
     readonly environment?: unknown;
     readonly logger?: Logger;
     readonly forceShutdownTimeoutMs?: number;
+    readonly instrumentation?: RuntimeInstrumentation;
 } & BootstrapArguments<TDefinition>;
 export declare function createKernelApplication<const TDefinition extends ApplicationDefinition>(options: KernelApplicationOptions<TDefinition>): KernelHostedApplication<TDefinition>;
 export declare function bootstrapApplication<const TDefinition extends ApplicationDefinition>(options: KernelApplicationOptions<TDefinition>): Promise<KernelHostedApplication<TDefinition>>;

package/dist/core/extension.d.ts

@@ -1,4 +1,5 @@
 import type { Diagnostic } from './diagnostic.js';
+import type { RuntimeExecutionMetadata, RuntimeInvocationRegistration, RuntimeOperationMetadata } from './instrumentation.js';
 import type { TokenLike } from './token.js';
 declare const runtimeCapabilityValue: unique symbol;
 declare const executionExtensionTypeInfo: unique symbol;
@@ -27,11 +28,21 @@ export declare class RuntimeCapabilityRegistry implements RuntimeCapabilityBindi
 }
 export interface ExecutionLease {
     readonly signal: AbortSignal;
+    run?<T>(operation: () => T): T;
     abort(reason?: unknown): void;
-    complete(): void;
+    fail?(reason: unknown): void;
+    annotate?(attributes: Readonly<Record<string, unknown>>): void;
+    complete(...result: [] | [unknown]): void;
+}
+export interface ExecutionOperationLease {
+    run?<T>(operation: () => T): T;
+    fail?(reason: unknown): void;
+    annotate?(attributes: Readonly<Record<string, unknown>>): void;
+    complete(...result: [] | [unknown]): void;
 }
 export interface ExecutionKernelRuntime {
-    beginExecution(): ExecutionLease;
+    beginExecution(metadata?: RuntimeExecutionMetadata, invocation?: RuntimeInvocationRegistration): ExecutionLease;
+    beginOperation?(metadata: RuntimeOperationMetadata, invocation?: RuntimeInvocationRegistration): ExecutionOperationLease;
     resolve<TValue>(token: TokenLike<TValue>, source?: string): TValue;
 }
 export interface ExecutionExtensionDrainContext {

package/dist/core/index.d.ts

@@ -7,7 +7,8 @@ export type { EnvClass, EnvKey, EnvSchema } from './env.js';
 export { defineError, DomainError } from './error.js';
 export type { ErrorDefinition } from './error.js';
 export { bindRuntimeCapability, defineExecution, defineExecutionExtension, executionDefinitionBrand, isExecutionDefinition, runtimeCapability, RuntimeCapabilityRegistry, } from './extension.js';
-export type { AnyExecutionExtension, ExecutionCompileContext, ExecutionContribution, ExecutionDefinition, ExecutionExtension, ExecutionExtensionDrainContext, ExecutionExtensionRuntime, ExecutionExtensionRuntimeContext, ExecutionExtensionValidationContext, ExecutionKernelRuntime, ExecutionLease, ExecutionProjectionContext, ExtensionOfDefinition, HostApiOfExtension, HostExtension, HostExtensionContext, RuntimeCapability, RuntimeCapabilityBinding, RuntimeCapabilityBindings, RuntimeCapabilityValue, } from './extension.js';
+export type { AnyExecutionExtension, ExecutionCompileContext, ExecutionContribution, ExecutionDefinition, ExecutionExtension, ExecutionExtensionDrainContext, ExecutionExtensionRuntime, ExecutionExtensionRuntimeContext, ExecutionExtensionValidationContext, ExecutionKernelRuntime, ExecutionLease, ExecutionProjectionContext, ExecutionOperationLease, ExtensionOfDefinition, HostApiOfExtension, HostExtension, HostExtensionContext, RuntimeCapability, RuntimeCapabilityBinding, RuntimeCapabilityBindings, RuntimeCapabilityValue, } from './extension.js';
+export type { RuntimeExecutionMetadata, RuntimeInstrumentation, RuntimeInstrumentationScope, RuntimeInvocationRegistration, RuntimeProviderMetadata, RuntimeOperationMetadata, } from './instrumentation.js';
 export { composeLayers, defineLayer } from './generic-layer.js';
 export type { GenericLayer, GenericLayerContext, GenericLayerNext, } from './generic-layer.js';
 export { collectInjectedDependencies, inject, InjectionContextError, runInInjectionContext, } from './injection.js';

package/dist/core/instrumentation.d.ts

@@ -0,0 +1,36 @@
+import type { Scope } from './provider.js';
+export interface RuntimeInvocationRegistration {
+    readonly input: unknown;
+    invoke(input: unknown): unknown | Promise<unknown>;
+}
+export interface RuntimeExecutionMetadata {
+    readonly executionId: string;
+    readonly executionKind: string;
+    readonly name?: string;
+    readonly graphNodeId?: string;
+}
+export interface RuntimeOperationMetadata {
+    readonly kind: string;
+    readonly name: string;
+    readonly graphNodeId?: string;
+}
+export interface RuntimeProviderMetadata {
+    readonly providerId: string;
+    readonly name: string;
+    readonly graphNodeId: string;
+    readonly scope: Scope;
+    readonly providerKind: 'value' | 'class' | 'factory' | 'conditional' | 'environment' | 'arguments';
+}
+export interface RuntimeInstrumentationScope {
+    run?<T>(operation: () => T): T;
+    abort?(reason?: unknown): void;
+    fail?(reason: unknown): void;
+    annotate?(attributes: Readonly<Record<string, unknown>>): void;
+    complete(...result: [] | [unknown]): void;
+}
+export interface RuntimeInstrumentation {
+    beginExecution?(metadata: RuntimeExecutionMetadata, invocation?: RuntimeInvocationRegistration): RuntimeInstrumentationScope | undefined;
+    beginOperation?(metadata: RuntimeOperationMetadata, invocation?: RuntimeInvocationRegistration): RuntimeInstrumentationScope | undefined;
+    providerCreated?(metadata: RuntimeProviderMetadata, value: unknown): void;
+    close?(): void | Promise<void>;
+}

package/dist/core/instrumentation.js

@@ -0,0 +1 @@
+export {};

package/dist/devtools/capsule.d.ts

@@ -0,0 +1,51 @@
+import type { RuntimeExecutionMetadata } from '../core/instrumentation.js';
+import type { DevtoolsModuleOptions } from './module.js';
+import type { ReplayCapsuleRequest, ReplayExecutionContext, RuntimeInvocationResult } from './inspector.js';
+import { type DevtoolsValuePreview } from './values.js';
+export interface ReplayRegistration {
+    readonly input: unknown;
+    replay(input: unknown, context: ReplayExecutionContext): unknown | Promise<unknown>;
+}
+export type CapturedValue = {
+    readonly mode: 'snapshot';
+    readonly value: unknown;
+} | {
+    readonly mode: 'reference';
+    readonly handleId: string;
+} | {
+    readonly mode: 'unavailable';
+    readonly reason: string;
+};
+export interface ExecutionReplayCapsulePreview {
+    readonly id: string;
+    readonly kind: 'execution';
+    readonly runId: string;
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly createdAt: number;
+    readonly expiresAt: number;
+    readonly execution: {
+        readonly executionId: string;
+        readonly executionKind: string;
+        readonly graphNodeId?: string;
+        readonly name: string;
+    };
+    readonly input: DevtoolsValuePreview;
+    readonly fidelity: 'snapshot' | 'reference' | 'unavailable';
+    readonly replayModes: readonly ['direct'];
+}
+export interface ReplayCapsuleStoreOptions {
+    readonly ttlMs?: number;
+    readonly maxCapsules?: number;
+    readonly capture?: DevtoolsModuleOptions['capture'];
+    readonly redact?: readonly string[];
+}
+export declare class ReplayCapsuleStore {
+    #private;
+    constructor(runId: string, options?: ReplayCapsuleStoreOptions);
+    createExecution(traceId: string, spanId: string, observation: RuntimeExecutionMetadata, registration: ReplayRegistration): ExecutionReplayCapsulePreview;
+    preview(capsuleId: string): ExecutionReplayCapsulePreview | undefined;
+    replay(request: ReplayCapsuleRequest): Promise<RuntimeInvocationResult>;
+    discard(capsuleId: string): void;
+    clear(): void;
+}

package/dist/devtools/capsule.js

@@ -0,0 +1,245 @@
+import { serializeDevtoolsError } from './observer.js';
+import { previewDevtoolsValue } from './values.js';
+const defaultCapsuleTtlMs = 5 * 60_000;
+const defaultMaxCapsules = 1_000;
+export class ReplayCapsuleStore {
+    #runId;
+    #ttlMs;
+    #maxCapsules;
+    #capture;
+    #redact;
+    #capsules = new Map();
+    #references = new Map();
+    constructor(runId, options = {}) {
+        this.#runId = runId;
+        this.#ttlMs = options.ttlMs ?? defaultCapsuleTtlMs;
+        this.#maxCapsules = options.maxCapsules ?? defaultMaxCapsules;
+        this.#capture = options.capture;
+        this.#redact = options.redact ?? [];
+        if (!Number.isFinite(this.#ttlMs) || this.#ttlMs <= 0) {
+            throw new TypeError('capsuleTtlMs must be a positive finite number.');
+        }
+        if (!Number.isInteger(this.#maxCapsules) || this.#maxCapsules < 1) {
+            throw new TypeError('maxCapsules must be a positive integer.');
+        }
+    }
+    createExecution(traceId, spanId, observation, registration) {
+        this.#purgeExpired();
+        const id = `capsule_${crypto.randomUUID()}`;
+        const createdAt = Date.now();
+        const captured = this.#captureValue(registration.input);
+        const preview = {
+            id,
+            kind: 'execution',
+            runId: this.#runId,
+            traceId,
+            spanId,
+            createdAt,
+            expiresAt: createdAt + this.#ttlMs,
+            execution: {
+                executionId: observation.executionId,
+                executionKind: observation.executionKind,
+                name: observation.name ?? observation.executionId,
+                ...(observation.graphNodeId === undefined
+                    ? {}
+                    : { graphNodeId: observation.graphNodeId }),
+            },
+            input: previewDevtoolsValue(registration.input, {
+                ...(this.#capture?.maxValueBytes === undefined
+                    ? {}
+                    : { maxValueBytes: this.#capture.maxValueBytes }),
+                ...(this.#capture?.maxDepth === undefined
+                    ? {}
+                    : { maxDepth: this.#capture.maxDepth }),
+                redact: this.#redact,
+            }),
+            fidelity: captured.mode,
+            replayModes: ['direct'],
+        };
+        this.#capsules.set(id, { preview, captured, replay: registration.replay });
+        while (this.#capsules.size > this.#maxCapsules) {
+            const oldest = this.#capsules.keys().next().value;
+            if (!oldest)
+                break;
+            this.#delete(oldest);
+        }
+        return preview;
+    }
+    preview(capsuleId) {
+        this.#purgeExpired();
+        return this.#capsules.get(capsuleId)?.preview;
+    }
+    async replay(request) {
+        this.#purgeExpired();
+        const capsule = this.#capsules.get(request.capsuleId);
+        if (!capsule) {
+            return {
+                requestId: request.requestId,
+                status: 'error',
+                error: {
+                    name: 'ReplayCapsuleUnavailableError',
+                    message: `LUTRE_DEVTOOLS_CAPSULE_UNAVAILABLE: ${request.capsuleId}`,
+                },
+            };
+        }
+        let input;
+        try {
+            input =
+                'inputOverride' in request
+                    ? request.inputOverride
+                    : this.#restore(capsule.captured);
+        }
+        catch (error) {
+            return {
+                requestId: request.requestId,
+                status: 'error',
+                error: serializeDevtoolsError(error),
+            };
+        }
+        const context = {
+            sourceTraceId: capsule.preview.traceId,
+            sourceCapsuleId: capsule.preview.id,
+            ...(request.parentTraceId === undefined
+                ? {}
+                : { parentTraceId: request.parentTraceId }),
+        };
+        try {
+            const result = await capsule.replay(input, context);
+            return {
+                requestId: request.requestId,
+                status: 'ok',
+                result: previewDevtoolsValue(result, {
+                    ...(this.#capture?.maxValueBytes === undefined
+                        ? {}
+                        : { maxValueBytes: this.#capture.maxValueBytes }),
+                    ...(this.#capture?.maxDepth === undefined
+                        ? {}
+                        : { maxDepth: this.#capture.maxDepth }),
+                    redact: this.#redact,
+                }),
+            };
+        }
+        catch (error) {
+            return {
+                requestId: request.requestId,
+                status: 'error',
+                error: serializeDevtoolsError(error),
+            };
+        }
+    }
+    discard(capsuleId) {
+        this.#delete(capsuleId);
+    }
+    clear() {
+        this.#capsules.clear();
+        this.#references.clear();
+    }
+    #captureValue(value) {
+        try {
+            if (isSnapshotCandidate(value)) {
+                return { mode: 'snapshot', value: structuredClone(value) };
+            }
+        }
+        catch {
+            // cloneできない値を失うより、同一process内だけで有効な参照として保持する。
+        }
+        if (value !== undefined) {
+            const handleId = `ref_${crypto.randomUUID()}`;
+            this.#references.set(handleId, value);
+            return { mode: 'reference', handleId };
+        }
+        return { mode: 'snapshot', value: undefined };
+    }
+    #restore(captured) {
+        switch (captured.mode) {
+            case 'snapshot':
+                return structuredClone(captured.value);
+            case 'reference':
+                if (this.#references.has(captured.handleId)) {
+                    return this.#references.get(captured.handleId);
+                }
+                throw new Error(`LUTRE_DEVTOOLS_REFERENCE_UNAVAILABLE: ${captured.handleId}`);
+            case 'unavailable':
+                throw new Error(`LUTRE_DEVTOOLS_CAPTURE_UNAVAILABLE: ${captured.reason}`);
+        }
+    }
+    #purgeExpired() {
+        const now = Date.now();
+        for (const [id, capsule] of this.#capsules) {
+            if (capsule.preview.expiresAt > now)
+                continue;
+            this.#delete(id);
+        }
+    }
+    #delete(id) {
+        const capsule = this.#capsules.get(id);
+        if (!capsule)
+            return;
+        if (capsule.captured.mode === 'reference') {
+            this.#references.delete(capsule.captured.handleId);
+        }
+        this.#capsules.delete(id);
+    }
+}
+function isSnapshotCandidate(value, seen = new WeakSet()) {
+    if (value === null)
+        return true;
+    if (typeof value === 'undefined' ||
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        typeof value === 'bigint') {
+        return true;
+    }
+    if (typeof value !== 'object')
+        return false;
+    if (seen.has(value))
+        return true;
+    seen.add(value);
+    try {
+        if (value instanceof Date ||
+            value instanceof ArrayBuffer ||
+            ArrayBuffer.isView(value)) {
+            return true;
+        }
+        if (Array.isArray(value)) {
+            return dataPropertiesAreSnapshotCandidates(value, seen, 'length');
+        }
+        if (value instanceof Map) {
+            for (const [key, item] of Map.prototype.entries.call(value)) {
+                if (!isSnapshotCandidate(key, seen) ||
+                    !isSnapshotCandidate(item, seen)) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        if (value instanceof Set) {
+            for (const item of Set.prototype.values.call(value)) {
+                if (!isSnapshotCandidate(item, seen))
+                    return false;
+            }
+            return true;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return false;
+        return dataPropertiesAreSnapshotCandidates(value, seen);
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+function dataPropertiesAreSnapshotCandidates(value, seen, ignoredKey) {
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    for (const key of Reflect.ownKeys(descriptors)) {
+        if (key === ignoredKey)
+            continue;
+        const descriptor = descriptors[key];
+        if (!descriptor || !('value' in descriptor))
+            return false;
+        if (!isSnapshotCandidate(descriptor.value, seen))
+            return false;
+    }
+    return true;
+}

package/dist/devtools/index.d.ts

@@ -0,0 +1,11 @@
+export { DEVTOOLS_PROTOCOL_VERSION } from './protocol.js';
+export { DevtoolsModule, devtoolsOptionsOf } from './module.js';
+export type { DevtoolsModuleOptions } from './module.js';
+export { ReplayCapsuleStore, type CapturedValue, type ExecutionReplayCapsulePreview, type ReplayCapsuleStoreOptions, } from './capsule.js';
+export type { ProviderMethodInvocationRequest, ProviderPlaygroundDescriptor, ProviderPlaygroundMethod, ProviderPlaygroundRequest, ReplayCapsuleRequest, ReplayExecutionContext, RuntimeDevtoolsContext, RuntimeDevtoolsContextStorage, RuntimeInspector, RuntimeInvocationResult, RuntimeTraceContext, } from './inspector.js';
+export { RuntimeDevtoolsInstrumentation } from './runtime.js';
+export type { RuntimeDevtoolsInstrumentationOptions } from './runtime.js';
+export type { ExecutionEndedEvent, ExecutionStartedEvent, RuntimeEvent, RuntimeEventBase, RuntimeObserver, RuntimeSpanKind, SerializedDevtoolsError, SpanEndedEvent, SpanStartedEvent, } from './observer.js';
+export { serializeDevtoolsError } from './observer.js';
+export type { DevtoolsValue, DevtoolsValuePreview, DevtoolsValuePreviewOptions, } from './values.js';
+export { previewDevtoolsValue } from './values.js';

package/dist/devtools/index.js

@@ -0,0 +1,6 @@
+export { DEVTOOLS_PROTOCOL_VERSION } from './protocol.js';
+export { DevtoolsModule, devtoolsOptionsOf } from './module.js';
+export { ReplayCapsuleStore, } from './capsule.js';
+export { RuntimeDevtoolsInstrumentation } from './runtime.js';
+export { serializeDevtoolsError } from './observer.js';
+export { previewDevtoolsValue } from './values.js';

package/dist/devtools/inspector.d.ts

@@ -0,0 +1,57 @@
+import type { SerializedDevtoolsError } from './observer.js';
+import type { DevtoolsValuePreview } from './values.js';
+export interface ReplayExecutionContext {
+    readonly sourceTraceId: string;
+    readonly sourceCapsuleId: string;
+    readonly parentTraceId?: string;
+}
+export interface ReplayCapsuleRequest {
+    readonly requestId: string;
+    readonly capsuleId: string;
+    readonly inputOverride?: unknown;
+    readonly parentTraceId?: string;
+}
+export interface ProviderPlaygroundRequest {
+    readonly requestId: string;
+    readonly graphNodeId: string;
+}
+export interface ProviderMethodInvocationRequest {
+    readonly requestId: string;
+    readonly graphNodeId: string;
+    readonly method: string;
+    readonly args: readonly unknown[];
+}
+export interface ProviderPlaygroundMethod {
+    readonly name: string;
+    readonly arity: number;
+}
+export interface ProviderPlaygroundDescriptor {
+    readonly requestId: string;
+    readonly graphNodeId: string;
+    readonly providerName: string;
+    readonly methods: readonly ProviderPlaygroundMethod[];
+}
+export interface RuntimeInvocationResult {
+    readonly requestId: string;
+    readonly status: 'ok' | 'error';
+    readonly traceId?: string;
+    readonly result?: DevtoolsValuePreview;
+    readonly error?: SerializedDevtoolsError;
+}
+export interface RuntimeInspector {
+    replayCapsule(request: ReplayCapsuleRequest): Promise<RuntimeInvocationResult>;
+    providerPlayground(request: ProviderPlaygroundRequest): Promise<ProviderPlaygroundDescriptor>;
+    invokeProviderMethod(request: ProviderMethodInvocationRequest): Promise<RuntimeInvocationResult>;
+}
+export interface RuntimeTraceContext {
+    readonly traceId: string;
+    readonly spanId: string;
+}
+export interface RuntimeDevtoolsContext {
+    readonly trace?: RuntimeTraceContext;
+    readonly replay?: ReplayExecutionContext;
+}
+export interface RuntimeDevtoolsContextStorage {
+    run<T>(context: RuntimeDevtoolsContext, operation: () => T): T;
+    current(): RuntimeDevtoolsContext | undefined;
+}

package/dist/devtools/inspector.js

@@ -0,0 +1 @@
+export {};

package/dist/devtools/module.d.ts

@@ -0,0 +1,18 @@
+import type { ApplicationModel } from '../core/model/types.js';
+export interface DevtoolsModuleOptions {
+    readonly enabled?: boolean;
+    readonly capture?: {
+        readonly providerMethods?: boolean;
+        readonly results?: false | 'errors' | 'all';
+        readonly maxValueBytes?: number;
+        readonly maxDepth?: number;
+    };
+    readonly replay?: {
+        readonly enabled?: boolean;
+        readonly capsuleTtlMs?: number;
+        readonly maxCapsules?: number;
+    };
+    readonly redact?: readonly string[];
+}
+export declare function DevtoolsModule(options?: DevtoolsModuleOptions): import("../core/module.js").ModuleInstance<import("../core/module.js").ModuleDefinition>;
+export declare function devtoolsOptionsOf(model: ApplicationModel): Readonly<DevtoolsModuleOptions> | undefined;

package/dist/devtools/module.js

@@ -0,0 +1,26 @@
+import { defineModule } from '../core/module.js';
+import { provide } from '../core/provider.js';
+import { token } from '../core/token.js';
+const devtoolsOptionsToken = token('loutre.devtools.options');
+const devtoolsModuleTemplate = defineModule((options = {}) => ({
+    name: 'LoutreDevtoolsModule',
+    providers: [
+        provide(devtoolsOptionsToken).useValue(Object.freeze({ ...options })),
+    ],
+}));
+export function DevtoolsModule(options) {
+    return devtoolsModuleTemplate(options);
+}
+export function devtoolsOptionsOf(model) {
+    const provider = model.providers.find((candidate) => {
+        if (candidate.kind !== 'value')
+            return false;
+        const provided = candidate.provide;
+        return (typeof provided !== 'function' &&
+            provided.kind === 'token' &&
+            provided.id === devtoolsOptionsToken.id);
+    });
+    return provider?.kind === 'value'
+        ? provider.useValue
+        : undefined;
+}

package/dist/devtools/observer.d.ts

@@ -0,0 +1,77 @@
+import type { RuntimeExecutionMetadata } from '../core/instrumentation.js';
+import type { DevtoolsValuePreview } from './values.js';
+export type RuntimeSpanKind = 'execution' | 'http.request' | 'http.middleware' | 'http.handler' | 'task.handler' | 'message-port.handler' | 'websocket.handler' | 'di.resolve' | 'provider.construct' | 'provider.method' | 'response' | 'dependency' | 'custom';
+export interface SerializedDevtoolsError {
+    readonly name?: string;
+    readonly message: string;
+    readonly stack?: string;
+}
+export interface RuntimeEventBase {
+    readonly runId: string;
+    readonly seq: number;
+    readonly timestamp: number;
+    readonly traceId?: string;
+    readonly spanId?: string;
+    readonly parentSpanId?: string;
+    readonly graphNodeId?: string;
+}
+export interface ExecutionStartedEvent extends RuntimeEventBase {
+    readonly type: 'execution.started';
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly executionId: string;
+    readonly executionKind: string;
+    readonly name: string;
+    readonly input?: DevtoolsValuePreview;
+    readonly capsuleId?: string;
+    readonly replayable?: boolean;
+    readonly replayModes?: readonly ('direct' | 'transport')[];
+    readonly replayedFromTraceId?: string;
+    readonly replayedFromCapsuleId?: string;
+}
+export interface ExecutionEndedEvent extends RuntimeEventBase {
+    readonly type: 'execution.ended';
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly executionId: string;
+    readonly durationMs: number;
+    readonly status: 'ok' | 'error' | 'cancelled';
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    readonly result?: DevtoolsValuePreview;
+    readonly error?: SerializedDevtoolsError;
+}
+export interface SpanStartedEvent extends RuntimeEventBase {
+    readonly type: 'span.started';
+    readonly spanId: string;
+    readonly traceId: string;
+    readonly kind: RuntimeSpanKind;
+    readonly name: string;
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    readonly input?: DevtoolsValuePreview;
+    readonly capsuleId?: string;
+    readonly replayable?: boolean;
+    readonly replayModes?: readonly ('direct' | 'transport')[];
+}
+export interface SpanEndedEvent extends RuntimeEventBase {
+    readonly type: 'span.ended';
+    readonly spanId: string;
+    readonly traceId: string;
+    readonly durationMs: number;
+    readonly status: 'ok' | 'error' | 'cancelled';
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    readonly result?: DevtoolsValuePreview;
+    readonly error?: SerializedDevtoolsError;
+}
+export type RuntimeEvent = ExecutionStartedEvent | ExecutionEndedEvent | SpanStartedEvent | SpanEndedEvent;
+export interface RuntimeObserver {
+    readonly runId?: string;
+    executionStarted?(event: ExecutionStartedEvent): void;
+    executionEnded?(event: ExecutionEndedEvent): void;
+    spanStarted?(event: SpanStartedEvent): void;
+    spanEnded?(event: SpanEndedEvent): void;
+}
+export interface RuntimeExecutionContext extends RuntimeExecutionMetadata {
+    readonly traceId: string;
+    readonly spanId: string;
+}
+export declare function serializeDevtoolsError(error: unknown): SerializedDevtoolsError;

package/dist/devtools/observer.js

@@ -0,0 +1,10 @@
+export function serializeDevtoolsError(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            ...(error.stack === undefined ? {} : { stack: error.stack }),
+        };
+    }
+    return { message: String(error) };
+}

package/dist/devtools/protocol.d.ts

@@ -0,0 +1 @@
+export declare const DEVTOOLS_PROTOCOL_VERSION = 1;

package/dist/devtools/protocol.js

@@ -0,0 +1 @@
+export const DEVTOOLS_PROTOCOL_VERSION = 1;

package/dist/devtools/provider-instrumentation.d.ts

@@ -0,0 +1,14 @@
+export interface ProviderMethodInvocation {
+    readonly key: PropertyKey;
+    readonly name: string;
+    readonly original: Function;
+    readonly receiver: unknown;
+    readonly args: readonly unknown[];
+}
+export interface ProviderMethodDefinition {
+    readonly key: PropertyKey;
+    readonly name: string;
+    readonly original: Function;
+}
+export declare function discoverProviderMethods(instance: object): readonly ProviderMethodDefinition[];
+export declare function instrumentProviderMethods(instance: object, invoke: (invocation: ProviderMethodInvocation) => unknown): () => void;