effect-inspect 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { Command } from 'effect/unstable/cli';
+export declare const cli: Command.Command<"effect-inspect", {}, {}, import("effect/Config").ConfigError | import("effect/unstable/http/HttpServerError").ServeError, import("effect/Scope").Scope>;

package/dist/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import * as NodeHttpServer from '@effect/platform-node/NodeHttpServer';
+import * as NodeRuntime from '@effect/platform-node/NodeRuntime';
+import * as NodeServices from '@effect/platform-node/NodeServices';
+// NodeHttpServer needs a native server constructor to own the HTTP and upgrade listeners.
+// oxlint-disable-next-line effecttsgo/node-builtin-import
+import { createServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
+import { Effect, Layer, Schema } from 'effect';
+import { FileSystem } from 'effect/FileSystem';
+import { Command } from 'effect/unstable/cli';
+import { collectorConfig } from './collector/Config.js';
+import { run } from './collector/Server.js';
+import { layer as storeLayer } from './collector/Store.js';
+import { loadWebApp } from './collector/WebApp.js';
+const start = Command.make('start', {}, () => Effect.gen(function* () {
+    const { capacity, port } = yield* collectorConfig;
+    const fetch = yield* loadWebApp;
+    yield* Effect.logInfo(`effect-inspect listening at http://localhost:${port}`);
+    return yield* Effect.provide(run(fetch), Layer.mergeAll(storeLayer({ capacity }), NodeHttpServer.layer(createServer, { port })));
+})).pipe(Command.withDescription('Start the collector and web UI (configured by EFFECT_INSPECT_PORT and EFFECT_INSPECT_CAPACITY)'));
+export const cli = Command.make('effect-inspect').pipe(Command.withDescription('Inspect Effect programs'), Command.withSubcommands([start]));
+const main = Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    const packageJson = yield* fs.readFileString(fileURLToPath(new URL('../package.json', import.meta.url)));
+    const { version } = yield* Schema.decodeEffect(Schema.fromJsonString(Schema.Struct({ version: Schema.String })))(packageJson);
+    return yield* Command.run(cli, { version });
+});
+NodeRuntime.runMain(main.pipe(Effect.scoped, Effect.provide(NodeServices.layer)));

package/dist/client/Client.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The outbound half of the inspect layer: a bounded queue plus the fiber that
+ * drains it to the collector.
+ *
+ * The guarantee that shapes this module is that instrumenting a program must
+ * never break or slow it. So the producer side is a synchronous, non-blocking
+ * {@link InspectClient} `sendUnsafe` onto a sliding queue, and every transport
+ * concern — no collector listening, a mid-run disconnect, a consumer slower
+ * than the program — is confined to a background fiber whose failures are
+ * swallowed and retried. When the program outruns the socket the queue drops
+ * its oldest messages and reports the count, rather than growing without bound
+ * or pushing backpressure into the fibers being traced.
+ */
+import { Context, Effect, type Scope } from 'effect';
+import type { Socket } from 'effect/unstable/socket';
+import * as Protocol from '../protocol/Schema.ts';
+declare const InspectClient_base: Context.ServiceClass<InspectClient, "effect-inspect/client/InspectClient", {
+    readonly sessionId: Protocol.SessionId;
+    readonly sendUnsafe: (message: Protocol.ClientMessage) => void;
+}>;
+/**
+ * The sink the tracer and logger push telemetry into.
+ *
+ * `sendUnsafe` is deliberately synchronous and total: it is called from inside
+ * `Tracer.span`, `span.end` and a `Logger`, none of which can suspend or fail.
+ */
+export declare class InspectClient extends InspectClient_base {
+}
+/** Options accepted by the inspect layers. */
+export interface Options {
+    /** Name shown for this program in the webapp. Defaults to the entry script's file name. */
+    readonly programName?: string | undefined;
+    /** Outbound queue capacity, in messages. Defaults to 8192. */
+    readonly bufferSize?: number | undefined;
+    /**
+     * How often to sample `process.memoryUsage()`, in milliseconds. Defaults to
+     * 100. Set to `0` to record no memory at all.
+     *
+     * Ignored in a runtime without `process.memoryUsage` — a browser or an edge
+     * worker records nothing and says nothing about it.
+     */
+    readonly memoryIntervalMillis?: number | undefined;
+}
+/**
+ * Builds the client service and forks the fiber that owns the connection.
+ *
+ * The returned effect never fails and never waits for the collector: if it is
+ * unreachable the fiber retries in the background while `sendUnsafe` keeps
+ * accepting (and dropping) messages, so the host program is unaffected.
+ */
+export declare const make: (options?: Options) => Effect.Effect<InspectClient['Service'], never, Scope.Scope | Socket.Socket>;
+export {};

package/dist/client/Client.js

@@ -0,0 +1,224 @@
+/**
+ * The outbound half of the inspect layer: a bounded queue plus the fiber that
+ * drains it to the collector.
+ *
+ * The guarantee that shapes this module is that instrumenting a program must
+ * never break or slow it. So the producer side is a synchronous, non-blocking
+ * {@link InspectClient} `sendUnsafe` onto a sliding queue, and every transport
+ * concern — no collector listening, a mid-run disconnect, a consumer slower
+ * than the program — is confined to a background fiber whose failures are
+ * swallowed and retried. When the program outruns the socket the queue drops
+ * its oldest messages and reports the count, rather than growing without bound
+ * or pushing backpressure into the fibers being traced.
+ */
+import { Context, Duration, Effect, Latch, Queue, Schedule } from 'effect';
+import { Socket as SocketService } from 'effect/unstable/socket';
+import { clientCodec } from '../protocol/Codec.js';
+import * as Protocol from '../protocol/Schema.js';
+/** How many messages may be buffered before the oldest are dropped. */
+const defaultBufferSize = 8192;
+/** How often a `Ping` is sent, so the collector can see a quiet program is alive. */
+const pingInterval = Duration.seconds(3);
+/** How often `process.memoryUsage()` is sampled, unless told otherwise. */
+const defaultMemoryIntervalMillis = 100;
+/**
+ * How long shutdown waits for queued messages to reach the collector.
+ *
+ * Bounded because the alternative to a lost tail is a program that will not
+ * exit, and that is the worse failure.
+ */
+const flushTimeout = Duration.millis(250);
+/** Reconnect backoff: doubling from 250ms, capped so a late collector is still found. */
+const reconnectSchedule = Schedule.exponential(Duration.millis(250)).pipe(Schedule.modifyDelay(({ output }) => Effect.succeed(Duration.min(output, Duration.seconds(5)))));
+/**
+ * The sink the tracer and logger push telemetry into.
+ *
+ * `sendUnsafe` is deliberately synchronous and total: it is called from inside
+ * `Tracer.span`, `span.end` and a `Logger`, none of which can suspend or fail.
+ */
+export class InspectClient extends Context.Service()('effect-inspect/client/InspectClient') {
+}
+/**
+ * The name this program lists as.
+ *
+ * The entry script's **file name**, not its path: `argv[1]` is absolute, so the
+ * default used to list a program as `/Users/.../examples/webapp.ts` and fill
+ * the session list with the same prefix over and over.
+ */
+const programName = (options) => {
+    if (options?.programName !== undefined)
+        return options.programName;
+    const script = globalThis.process?.argv?.[1];
+    if (script === undefined || script === '')
+        return 'effect';
+    return script.split(/[/\\]/).pop() || script;
+};
+const runtimeName = () => {
+    const versions = globalThis.process?.versions;
+    if (versions?.bun !== undefined)
+        return `bun ${versions.bun}`;
+    if (versions?.node !== undefined)
+        return `node ${versions.node}`;
+    return 'unknown';
+};
+/**
+ * `process.memoryUsage`, or `undefined` in a runtime that has no such thing.
+ *
+ * Resolved once, at layer construction: the check is a property read, but doing
+ * it per sample would be a property read on the host program's hot path for a
+ * value that cannot change. A browser, Deno without `--allow-*`, or a Workers
+ * runtime lands on `undefined` and simply never samples — silently, forever,
+ * which is the whole contract here.
+ */
+const memoryUsage = () => {
+    const usage = globalThis.process?.memoryUsage;
+    return typeof usage === 'function' ? usage.bind(globalThis.process) : undefined;
+};
+/**
+ * Forks the fiber that samples process memory into the outbound queue.
+ *
+ * Deliberately the same shape as the `Ping` fiber: a delayed `forever` forked
+ * into the client's scope, so it dies with the layer and cannot keep a program
+ * alive past its own exit. Sampling rides `sendUnsafe` like everything else, so
+ * a full queue drops a sample rather than pushing back on the host — a gap in a
+ * memory curve is a far cheaper failure than a stalled program.
+ *
+ * Returns `void` and forks nothing when the runtime has no `process.memoryUsage`
+ * or the interval is not a positive number.
+ */
+const forkMemorySampler = (deps) => Effect.suspend(() => {
+    const usage = memoryUsage();
+    if (usage === undefined || !(deps.intervalMillis > 0))
+        return Effect.void;
+    const sample = Effect.clockWith((clock) => Effect.sync(() => {
+        const memory = usage();
+        deps.sendUnsafe({
+            _tag: 'MemorySample',
+            sessionId: deps.sessionId,
+            time: clock.currentTimeNanosUnsafe(),
+            // Rounded because the protocol's `Natural` rejects a fraction, and
+            // `rss` on some platforms is not an integer.
+            heapUsed: Math.round(memory.heapUsed),
+            heapTotal: Math.round(memory.heapTotal),
+            rss: Math.round(memory.rss),
+            external: Math.round(memory.external),
+        });
+    }));
+    return sample.pipe(Effect.delay(Duration.millis(deps.intervalMillis)), Effect.forever, Effect.forkScoped, Effect.asVoid);
+});
+/**
+ * Builds the client service and forks the fiber that owns the connection.
+ *
+ * The returned effect never fails and never waits for the collector: if it is
+ * unreachable the fiber retries in the background while `sendUnsafe` keeps
+ * accepting (and dropping) messages, so the host program is unaffected.
+ */
+export const make = (options) => Effect.gen(function* () {
+    const socket = yield* SocketService.Socket;
+    const capacity = options?.bufferSize ?? defaultBufferSize;
+    const queue = yield* Queue.sliding(capacity);
+    // Effect's `Crypto` can fail with a PlatformError and nothing on this path
+    // is allowed to fail; a session id needs uniqueness, not strength.
+    // oxlint-disable-next-line effecttsgo/crypto-random-uuid-in-effect
+    const sessionId = crypto.randomUUID();
+    // Tracked here rather than inside the queue so a drop survives a
+    // reconnect: it is reported on the next `Hello`, which every reconnect
+    // re-sends. A sliding `offerUnsafe` always succeeds, so a full queue is
+    // the only drop signal there is.
+    // Open exactly while the queue is empty, so shutdown can ask "is everything
+    // on the wire?" rather than guessing with a sleep.
+    const flushed = Latch.makeUnsafe(true);
+    let dropped = 0;
+    let reported = 0;
+    const sendUnsafe = (message) => {
+        if (Queue.sizeUnsafe(queue) >= capacity)
+            dropped += 1;
+        Queue.offerUnsafe(queue, message);
+        flushed.closeUnsafe();
+    };
+    const hello = Effect.clockWith((clock) => Effect.succeed({
+        _tag: 'Hello',
+        sessionId,
+        program: programName(options),
+        pid: globalThis.process?.pid ?? 0,
+        runtime: runtimeName(),
+        protocolVersion: Protocol.protocolVersion,
+        clock: {
+            startTime: clock.currentTimeNanosUnsafe(),
+            // Deliberately the wall clock: this is the anchor that maps the
+            // monotonic span clock onto absolute time, which is precisely what
+            // Effect's `Clock` is not.
+            // oxlint-disable-next-line effecttsgo/global-date
+            wallClockEpochMillis: Date.now(),
+        },
+    }));
+    // ponytail: drops are reported as a `Log`, not a dedicated protocol field.
+    // `Hello` has no dropped-count and the schema is frozen; a Warn log rides
+    // the same ordered stream the webapp already renders, so the gap is visible
+    // in place. Promote to a real field if the UI needs to count it separately.
+    const reportDropped = Effect.clockWith((clock) => Effect.sync(() => {
+        if (dropped === reported)
+            return undefined;
+        const gap = dropped - reported;
+        reported = dropped;
+        return {
+            _tag: 'Log',
+            sessionId,
+            time: clock.currentTimeNanosUnsafe(),
+            level: 'Warn',
+            message: `effect-inspect dropped ${gap} messages: the collector is slower than this program`,
+            annotations: { 'effect_inspect.dropped': gap, 'effect_inspect.droppedTotal': dropped },
+        };
+    }));
+    yield* connection({ socket, queue, sessionId, hello, reportDropped, flushed }).pipe(Effect.forkScoped);
+    yield* forkMemorySampler({
+        sendUnsafe,
+        sessionId,
+        intervalMillis: options?.memoryIntervalMillis ?? defaultMemoryIntervalMillis,
+    });
+    // A short program can finish before the socket has even opened, and closing
+    // the scope would otherwise interrupt the connection fiber mid-flight and
+    // lose the whole trace. So wait for the queue to drain — but only briefly,
+    // and never propagating a failure: a collector that has gone away must not
+    // become a program that will not exit.
+    yield* Effect.addFinalizer(() => Latch.await(flushed).pipe(Effect.timeoutOption(flushTimeout), Effect.ignore));
+    return InspectClient.of({ sessionId, sendUnsafe });
+});
+/**
+ * Holds one connection open: sends `Hello`, then pumps the queue until the
+ * socket fails, at which point the retry schedule dials again.
+ */
+const connection = (deps) => Effect.gen(function* () {
+    // The reader is what actually dials: a WebSocket `Socket` only connects
+    // when its reader is acquired, and until then every write parks waiting for
+    // a connection that will never be made. Acquiring it also surfaces the
+    // disconnect that drives the reconnect below.
+    const reader = yield* deps.socket.reader;
+    const writer = yield* deps.socket.writer;
+    const write = (message) => Effect.suspend(() => writer.write(clientCodec.encode(message)));
+    yield* Effect.flatMap(deps.hello, write);
+    // Keeps the connection warm and surfaces a half-open socket as a write
+    // failure, which is what triggers the reconnect.
+    yield* write({ _tag: 'Ping', sessionId: deps.sessionId }).pipe(Effect.delay(pingInterval), Effect.forever, Effect.forkScoped);
+    const pump = Effect.gen(function* () {
+        const batch = yield* Queue.takeAll(deps.queue);
+        // Announced before the batch, so the gap is ordered where it happened.
+        const gap = yield* deps.reportDropped;
+        if (gap !== undefined)
+            yield* write(gap);
+        yield* Effect.forEach(batch, write);
+        // Everything offered so far is on the wire. `sendUnsafe` closes the latch
+        // again on the next message, so this tracks the queue rather than latching
+        // permanently on the first quiet moment.
+        if (Queue.sizeUnsafe(deps.queue) === 0)
+            deps.flushed.openUnsafe();
+    });
+    // Raced rather than forked: a forked fiber's failure would not reach this
+    // scope, so a collector that goes away mid-run would be noticed only if the
+    // program happened to write again. Whichever side notices the disconnect
+    // first ends the connection, and the retry below dials the next one.
+    return yield* Effect.raceFirst(Effect.forever(pump), Effect.forever(reader.pull));
+}).pipe(Effect.scoped, 
+// Every failure here is the collector's, never the host program's: retry
+// forever, and if the retry itself somehow gives up, stay silent.
+Effect.retry(reconnectSchedule), Effect.ignore);

package/dist/client/Edge.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Edge conversions from Effect's runtime values to the wire protocol's bounded
+ * domain.
+ *
+ * The protocol deliberately refuses anything it cannot render: attribute values
+ * are a bounded {@link Protocol.Json} union, and `SpanEnd` carries a flattened
+ * outcome rather than a `Cause`. Both narrowings happen here, at the producer,
+ * so a decoder never has to guess and an exotic attribute value can never fail
+ * an encode mid-flight.
+ */
+import { type Exit } from 'effect';
+import type * as Protocol from '../protocol/Schema.ts';
+/**
+ * Coerces an arbitrary runtime value into the protocol's `Json` union.
+ *
+ * Everything outside the union — functions, symbols, bigints, class instances,
+ * `undefined`, and the non-finite numbers the codec rejects — is stringified.
+ * Cycles are replaced with `"[Circular]"` rather than throwing.
+ */
+export declare const toJson: (value: unknown) => Protocol.Json;
+/** Coerces a map or record of attributes into the protocol's bounded domain. */
+export declare const toAttributes: (entries: ReadonlyMap<string, unknown> | Readonly<Record<string, unknown>>) => Protocol.Attributes;
+/**
+ * Flattens an `Exit` into the protocol's `SpanOutcome`.
+ *
+ * The whole `Cause` is collapsed to a kind plus a rendered message: the webapp
+ * only needs to colour the span and show text. A cause carrying several reasons
+ * is classified by its most informative one — a real failure or defect outranks
+ * an interrupt, since interrupting siblings is how Effect unwinds a failure.
+ */
+export declare const toOutcome: (exit: Exit.Exit<unknown, unknown>) => Protocol.SpanOutcome;

package/dist/client/Edge.js

@@ -0,0 +1,108 @@
+/**
+ * Edge conversions from Effect's runtime values to the wire protocol's bounded
+ * domain.
+ *
+ * The protocol deliberately refuses anything it cannot render: attribute values
+ * are a bounded {@link Protocol.Json} union, and `SpanEnd` carries a flattened
+ * outcome rather than a `Cause`. Both narrowings happen here, at the producer,
+ * so a decoder never has to guess and an exotic attribute value can never fail
+ * an encode mid-flight.
+ */
+import { Cause } from 'effect';
+/**
+ * Coerces an arbitrary runtime value into the protocol's `Json` union.
+ *
+ * Everything outside the union — functions, symbols, bigints, class instances,
+ * `undefined`, and the non-finite numbers the codec rejects — is stringified.
+ * Cycles are replaced with `"[Circular]"` rather than throwing.
+ */
+export const toJson = (value) => jsonWithin(value, new Set());
+const jsonWithin = (value, seen) => {
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return value;
+        // `Infinity`/`NaN` are rejected by the codec, so they become text here.
+        case 'number':
+            return Number.isFinite(value) ? value : String(value);
+        case 'bigint':
+            return String(value);
+        case 'object':
+            break;
+        // function, symbol, undefined
+        default:
+            return stringify(value);
+    }
+    if (value === null)
+        return null;
+    if (seen.has(value))
+        return '[Circular]';
+    seen.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.map((item) => jsonWithin(item, seen));
+        if (isPlainObject(value)) {
+            const out = {};
+            for (const [key, item] of Object.entries(value))
+                out[key] = jsonWithin(item, seen);
+            return out;
+        }
+        // Dates, Errors, Maps, class instances: rendered, not structurally walked.
+        return stringify(value);
+    }
+    finally {
+        seen.delete(value);
+    }
+};
+const isPlainObject = (value) => {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+};
+const stringify = (value) => {
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'symbol' || typeof value === 'function')
+        return String(value);
+    try {
+        // `[object Object]` is an acceptable last resort; the alternative is
+        // dropping an attribute the user asked to see.
+        // oxlint-disable-next-line no-base-to-string
+        return value instanceof Error ? `${value.name}: ${value.message}` : String(value);
+    }
+    catch {
+        return '[unrenderable]';
+    }
+};
+/** Coerces a map or record of attributes into the protocol's bounded domain. */
+export const toAttributes = (entries) => {
+    const out = {};
+    const pairs = entries instanceof Map ? entries.entries() : Object.entries(entries);
+    for (const [key, value] of pairs)
+        out[key] = toJson(value);
+    return out;
+};
+/**
+ * Flattens an `Exit` into the protocol's `SpanOutcome`.
+ *
+ * The whole `Cause` is collapsed to a kind plus a rendered message: the webapp
+ * only needs to colour the span and show text. A cause carrying several reasons
+ * is classified by its most informative one — a real failure or defect outranks
+ * an interrupt, since interrupting siblings is how Effect unwinds a failure.
+ */
+export const toOutcome = (exit) => {
+    if (exit._tag === 'Success')
+        return { _tag: 'Success' };
+    const cause = exit.cause;
+    const reason = cause.reasons.find((candidate) => !Cause.isInterruptReason(candidate)) ?? cause.reasons[0];
+    if (reason === undefined)
+        return { _tag: 'Failure', kind: 'Interrupt', error: 'Interrupted' };
+    const kind = reason._tag;
+    const stack = stackOf(Cause.isFailReason(reason) ? reason.error : undefined);
+    return {
+        _tag: 'Failure',
+        kind,
+        error: Cause.pretty(cause),
+        ...(stack === undefined ? {} : { stack }),
+    };
+};
+const stackOf = (error) => error instanceof Error && typeof error.stack === 'string' ? error.stack : undefined;

package/dist/client/Inspect.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The layer a user adds to an Effect program to stream it to effect-inspect.
+ *
+ * ```ts
+ * import { Effect } from 'effect'
+ * import { Inspect } from 'effect-inspect'
+ *
+ * program.pipe(Effect.provide(Inspect.layer()))
+ * ```
+ *
+ * Adding this layer is safe in any environment: if no collector is listening
+ * the program runs exactly as it would have, without hanging, erroring, or
+ * waiting on a connection. See `Client.ts` for how that is kept true.
+ */
+import { Layer } from 'effect';
+import { Socket } from 'effect/unstable/socket';
+import * as Client from './Client.ts';
+export type { Options } from './Client.ts';
+export { InspectClient } from './Client.ts';
+/** Where the collector listens unless told otherwise. */
+export declare const defaultUrl = "ws://localhost:34437";
+/**
+ * Installs the inspect tracer and logger over an existing `Socket`.
+ *
+ * Use when the transport is already established — a test harness, or a
+ * collector reached over something other than a WebSocket.
+ *
+ * The logger is merged into the program's existing loggers rather than
+ * replacing them, so console output is untouched.
+ */
+export declare const layerSocket: (options?: Client.Options) => Layer.Layer<never, never, Socket.Socket>;
+/**
+ * Installs the inspect tracer and logger over a WebSocket to `url`.
+ *
+ * Requires a `Socket.WebSocketConstructor`; {@link layer} is the version that
+ * supplies the global one for you.
+ */
+export declare const layerWebSocket: (options?: Client.Options & {
+    readonly url?: string;
+}) => Layer.Layer<never, never, Socket.WebSocketConstructor>;
+/**
+ * Installs the inspect tracer and logger over a WebSocket, using the runtime's
+ * global `WebSocket`.
+ *
+ * This is the entry point most programs want.
+ */
+export declare const layer: (options?: Client.Options & {
+    readonly url?: string;
+}) => Layer.Layer<never>;

package/dist/client/Inspect.js

@@ -0,0 +1,55 @@
+/**
+ * The layer a user adds to an Effect program to stream it to effect-inspect.
+ *
+ * ```ts
+ * import { Effect } from 'effect'
+ * import { Inspect } from 'effect-inspect'
+ *
+ * program.pipe(Effect.provide(Inspect.layer()))
+ * ```
+ *
+ * Adding this layer is safe in any environment: if no collector is listening
+ * the program runs exactly as it would have, without hanging, erroring, or
+ * waiting on a connection. See `Client.ts` for how that is kept true.
+ */
+import { Layer, Logger, Tracer } from 'effect';
+import { Socket } from 'effect/unstable/socket';
+import * as Client from './Client.js';
+import * as ClientTracer from './Tracer.js';
+export { InspectClient } from './Client.js';
+// ponytail: no `FiberEvent` is emitted. The only public hook is
+// `Metric.FiberRuntimeMetricsService`, whose `recordFiberStart`/`recordFiberEnd`
+// receive a `Context` and an `Exit` but no fiber id — and it has nothing for
+// Suspend/Resume at all. Emitting the protocol's `FiberEvent` from it would
+// mean patching runtime internals for data M1 does not render anyway. Revisit
+// when Effect exposes fiber ids on that service.
+/** Where the collector listens unless told otherwise. */
+export const defaultUrl = 'ws://localhost:34437';
+/** Provides the queue and connection the tracer and logger both write into. */
+const layerClient = (options) => Layer.effect(Client.InspectClient)(Client.make(options));
+/**
+ * Installs the inspect tracer and logger over an existing `Socket`.
+ *
+ * Use when the transport is already established — a test harness, or a
+ * collector reached over something other than a WebSocket.
+ *
+ * The logger is merged into the program's existing loggers rather than
+ * replacing them, so console output is untouched.
+ */
+export const layerSocket = (options) => Layer.merge(Layer.effect(Tracer.Tracer)(Client.InspectClient.use(ClientTracer.make)), Logger.layer([Client.InspectClient.useSync(ClientTracer.makeLogger)], {
+    mergeWithExisting: true,
+})).pipe(Layer.provide(layerClient(options)));
+/**
+ * Installs the inspect tracer and logger over a WebSocket to `url`.
+ *
+ * Requires a `Socket.WebSocketConstructor`; {@link layer} is the version that
+ * supplies the global one for you.
+ */
+export const layerWebSocket = (options) => layerSocket(options).pipe(Layer.provide(Socket.layerWebSocket(options?.url ?? defaultUrl)));
+/**
+ * Installs the inspect tracer and logger over a WebSocket, using the runtime's
+ * global `WebSocket`.
+ *
+ * This is the entry point most programs want.
+ */
+export const layer = (options) => layerWebSocket(options).pipe(Layer.provide(Socket.layerWebSocketConstructorGlobal));

package/dist/client/Tracer.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The tracer and logger that observe the host program.
+ *
+ * Both delegate rather than replace: the tracer wraps whatever tracer is
+ * already installed and the logger is merged into the existing set, so adding
+ * the inspect layer never removes behaviour the program already had. Every
+ * method here is called on the host program's own fibers, so none of them may
+ * fail, suspend, or do real work — they narrow a value to the protocol's domain
+ * and hand it to a queue.
+ */
+import { Effect, Logger, Tracer } from 'effect';
+import type { InspectClient } from './Client.ts';
+/**
+ * Creates a tracer that mirrors every span to the client while delegating to
+ * the current tracer.
+ *
+ * `SpanStart` is sent once when the span opens and `SpanEnd` when it closes,
+ * carrying the end time, the flattened outcome, and the span's attributes for
+ * the collector to merge. See `span` for why the attributes are not a strict
+ * delta.
+ */
+export declare const make: (client: InspectClient['Service']) => Effect.Effect<Tracer.Tracer>;
+/**
+ * Creates a logger that mirrors every log record to the client, correlated with
+ * the span the logging fiber is inside.
+ *
+ * Effect's own tracer logger turns logs into span events, which loses logs
+ * emitted outside any span. These are sent as `Log` instead, so they keep their
+ * level and appear in the stream whether or not a span was active.
+ */
+export declare const makeLogger: (client: InspectClient['Service']) => Logger.Logger<unknown, void>;