Standalone Inspector API

Generated public TypeScript reference for @relkit/inspector.

For configuration and examples, read inspector.

Public imports

• @relkit/inspector — 13 exports

All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API’s inline sample, a maintained repository usage, or the shared module walkthrough.

backend-forward.ts

Live operations are forwarded once; bridge rejections retain their HTTP status in the UI protocol.

forwardBackend

Preserves native cookies, authorization, operation IDs and streaming bodies.

Signature

declare const forwardBackend: (
  remote: InspectorRemoteOperations,
  connection: InspectionConnectionFile,
  request: Request,
  target?: string | undefined,
) => Effect.Effect<Response, InspectionConnectionError, never>;

Source

backend-history.ts

History queries stay in the standalone writer; no application config is executed.

backendError

Credential-free failures retain the UI’s established error protocol.

Signature

declare const backendError: (error: string, status: number) => Response;

Source

historyResponse

Decodes only supported query/detail paths and returns their existing public protocol.

Signature

declare const historyResponse: (
  current: InspectorToolState,
  request: Request,
  match: RegExpExecArray,
) => Effect.Effect<Response, InspectionConnectionError, never>;

Source

bin.ts

Native standalone entry; signals interrupt and join the tool’s complete resource Scope.

collection.schemas.ts

Validates network records again; in-process redaction brands are never trusted across JSON.

InspectionCollectionBatch

A finite batch has monotonic session sequence identities and optional producer attribution.

Signature

declare const InspectionCollectionBatch: Schema.fromJsonString<
  Schema.Struct<{
    readonly records: Schema.$Array<
      Schema.Struct<{
        readonly sequence: Schema.Number;
        readonly record: Schema.declare<ObservabilityRecord, ObservabilityRecord>;
        readonly identity: Schema.optionalKey<
          Schema.Struct<{
            readonly key: Schema.String;
            readonly origin: Schema.Literals<readonly ["application", "relkit", "inspector"]>;
          }>
        >;
      }>
    >;
    readonly gap: Schema.Boolean;
    readonly droppedRecords: Schema.Number;
    readonly incomplete: Schema.Boolean;
    readonly droppedBytes: Schema.optionalKey<Schema.Number>;
    readonly producerFailed: Schema.optionalKey<Schema.Number>;
    readonly producerDropped: Schema.optionalKey<Schema.Number>;
  }>
>;

Source

collector-changes.ts

Coalesces UI invalidations without retaining another copy of committed records.

collectionChange

Uses existing event names so current graph/history/job views refresh after commits.

Signature

declare const collectionChange: (record: ObservabilityRecord) => ObservabilityStreamEventType;

Source

collector-loss.ts

Cumulative loss has an independent durable identity, outside the saturated application’s buffer.

persistCollectionLoss

One tiny transaction follows record persistence; a lost ACK reuses the same receipt key.

Signature

declare const persistCollectionLoss: (
  history: InspectorHistoryOperations,
  batch: {
    readonly records: ReadonlyArray<{
      readonly record: ObservabilityRecord;
      readonly sequence: number;
      readonly identity?: {
        readonly key: string;
        readonly origin: "application" | "relkit" | "inspector";
      };
    }>;
    readonly gap: boolean;
    readonly droppedRecords: number;
    readonly incomplete: boolean;
    readonly droppedBytes?: number;
    readonly producerFailed?: number;
    readonly producerDropped?: number;
  },
  sessionId: string,
  previous?: string | undefined,
) => Effect.Effect<string | undefined, InspectionConnectionError, never>;

Source

collector.ts

Commits a finite replay batch before ACK; lost ACKs replay stable keys without duplicate writes.

collectInspectionBatch

One bounded pull needs no independent pending queue or in-memory history copy.

Signature

declare const collectInspectionBatch: (
  remote: InspectorRemoteOperations,
  history: InspectorHistoryOperations,
  connection: InspectionConnectionFile,
  after: number,
  target?: string | undefined,
  previousLossKey?: string | undefined,
) => Effect.Effect<
  {
    through: number;
    gap: boolean;
    droppedRecords: number;
    incomplete: boolean;
    records: number;
    lossKey: string | undefined;
    producerFailed: number;
    producerDropped: number;
    changes: Array<
      | "request.started"
      | "request.completed"
      | "log.emitted"
      | "span.started"
      | "span.updated"
      | "span.completed"
      | "job.changed"
      | "event.published"
      | "event.delivery.changed"
      | "generation.changed"
      | "diagnostic.changed"
    >;
  },
  InspectionConnectionError,
  never
>;

Source

container-bin.ts

Linux image entry requires explicit persistent mounts before acquiring the tool.

container-exit.ts

A joined requested shutdown is healthy; mixed failures retain normal failure exit codes.

inspectorContainerTeardown

Signature

declare const inspectorContainerTeardown: Runtime.Teardown;

Source

container-native.ts

Reads Linux mount authority only at the image’s explicit native entry.

requireInspectorContainer

Signature

declare const requireInspectorContainer: (
  options: InspectorOptions,
) => Effect.Effect<undefined, InspectionConnectionError, never>;

Source

container-policy.ts

Restricts image execution to a private directory mount and persistent history.

validateInspectorContainer

Signature

declare const validateInspectorContainer: (
  options: InspectorOptions,
  uid: number,
  mountInfo: string,
) => void;

Source

discovery.service.ts

Authenticates session discovery without executing project code or deleting stale metadata.

InspectorDiscovery (class)

Captures metadata and transport authority before creating any per-tool session state.

Signature

declare class InspectorDiscovery

Source

InspectorDiscoveryLive

Native discovery performs no config import, writes, installation or PID liveness probes.

Signature

declare const InspectorDiscoveryLive: Layer.Layer<InspectorDiscovery, never, never>;

Source

discovery.types.ts

Discovery results keep credentials private and never select by PID or file age.

InspectorDiscoveryOperations (interface)

Read-only discovery leaves stale and foreign descriptors untouched.

Signature

export interface InspectorDiscoveryOperations {
  readonly select: (
    options: InspectorOptions,
  ) => Effect.Effect<InspectorSelection, InspectionConnectionError>;
}

Source

InspectorSelection (type alias)

Only an authenticated matching handshake grants live forwarding authority.

Signature

type InspectorSelection =
  | { readonly state: "disconnected"; readonly rejected: number }
  | { readonly state: "ambiguous"; readonly sessions: readonly string[]; readonly rejected: number }
  | {
      readonly state: "connected";
      readonly connection: InspectionConnectionFile;
      readonly handshake: InspectionHandshake;
      readonly rejected: number;
    };

Source

history-binding.ts

Binds a history directory to one project without replacing existing data or deleting locks.

bindInspectorHistory

Publishes an immutable project marker atomically, retaining legacy history in place.

Signature

declare const bindInspectorHistory: (
  root: string,
  projectId: string,
) => Effect.Effect<undefined, InspectionConnectionError, never>;

Source

history-native.service.ts

Acquires the optional isolated writer and validates its opening receipt before exposing it.

InspectorHistoryNative (class)

Tests substitute the complete native boundary without inheriting live process authority.

Signature

declare class InspectorHistoryNative

Source

InspectorHistoryNativeLive

Native worker module is owned exclusively by the standalone tool.

Signature

declare const InspectorHistoryNativeLive: Layer.Layer<InspectorHistoryNative, never, never>;

Source

historyNativeFailure

Retains precise native failure evidence without exposing native payloads to browser responses.

Signature

declare const historyNativeFailure: <Cause extends Error>(
  cause: Cause,
) => InspectionConnectionError;

Source

history-native.types.ts

Native history acquisition is replaceable and retains caller lifetime authority.

InspectorHistoryNativeOperations (interface)

Owns project binding, worker open and joined physical shutdown as one acquisition.

Signature

export interface InspectorHistoryNativeOperations {
  readonly acquire: (
    root: string,
    projectId: string,
  ) => Effect.Effect<LocalWorkerEffects, InspectionConnectionError, Scope.Scope>;
}

Source

history-reply.ts

Validates native IPC payloads through the shared model/query owner before exposing browser data.

validateHistoryReply

A transport-level JSON decode alone cannot certify a worker query response.

Signature

declare const validateHistoryReply: (
  command: LocalWorkerCommand,
  value: Schema.Json | undefined,
) => Effect.Effect<void, InspectionConnectionError, never>;

Source

history.service.ts

Owns the existing isolated DuckDB worker and preserves its transactional receipt semantics.

InspectorHistory (class)

Persistent history opens only inside the standalone tool’s Scope.

Signature

declare class InspectorHistory

Source

inspectorHistoryLayer

Supplies exactly one native writer owner for the selected project.

Signature

declare const inspectorHistoryLayer: (
  root: string,
  projectId: string,
) => Layer.Layer<InspectorHistory, InspectionConnectionError, InspectorHistoryNative>;

Source

history.types.ts

Standalone history owns the native worker; the application receives only durable ACKs.

InspectorHistoryOperations (interface)

Serialized operations use the existing project store/schema and stable receipt keys.

Signature

export interface InspectorHistoryOperations {
  readonly call: (
    command: LocalWorkerCommand,
  ) => Effect.Effect<Schema.Json | undefined, InspectionConnectionError>;
}

Source

index.ts

Standalone tool entry; project inspection never evaluates application configuration.

INSPECTOR_HELP

Signature

declare const INSPECTOR_HELP: "Usage: relkit-inspector [options]\n  --project-root <directory>     Discover running sessions without evaluating the project\n  --connection-file <file>       Explicitly select one private session descriptor\n  --credential-file <file>       Private descriptor supplying matching session credentials\n  --target <http-origin>         Override network routing while verifying original identity\n  --history-directory <path>     Persistent project-bound history (default .relkit/observability)\n  --hostname <host>              UI bind host (default 127.0.0.1)\n  --port <number>                UI port (default 3210)\n  --help                        Show this help\n";

Source

InspectorDiscovery

Signature

declare const InspectorDiscovery: typeof InspectorDiscovery;

Source

InspectorDiscoveryLive

Signature

declare const InspectorDiscoveryLive: Layer<InspectorDiscovery, never, never>;

Source

InspectorHistory

Signature

declare const InspectorHistory: typeof InspectorHistory;

Source

InspectorHistoryNative

Signature

declare const InspectorHistoryNative: typeof InspectorHistoryNative;

Source

InspectorHistoryNativeLive

Signature

declare const InspectorHistoryNativeLive: Layer<InspectorHistoryNative, never, never>;

Source

InspectorOptions

Signature

declare const InspectorOptions: InspectorOptions;

Source

InspectorRemote

Signature

declare const InspectorRemote: typeof InspectorRemote;

Source

InspectorRemoteLive

Signature

declare const InspectorRemoteLive: Layer<InspectorRemote, never, never>;

Source

InspectorTool

Signature

declare const InspectorTool: typeof InspectorTool;

Source

InspectorToolLive

Signature

declare const InspectorToolLive: Layer<InspectorTool, never, never>;

Source

inspectorHistoryLayer

Signature

declare const inspectorHistoryLayer: (
  root: string,
  projectId: string,
) => Layer<InspectorHistory, InspectionConnectionError, InspectorHistoryNative>;

Source

parseInspectorOptions

Signature

declare const parseInspectorOptions: (args: readonly string[]) => InspectorOptions;

Source

live-events.ts

UI invalidations borrow the existing bounded stream, while full records stay in history.

acquireLiveEvents

The tool Scope closes every subscriber before releasing its listener.

Signature

declare const acquireLiveEvents: Effect.Effect<ObservabilityStream, never, Scope>;

Source

publishCollection

One small invalidation per signal follows the committed batch; no history copy is retained.

Signature

declare const publishCollection: (
  stream: ObservabilityStream,
  changes: readonly ObservabilityStreamEventType[],
) => void;

Source

publishSelection

Session/generation changes invalidate metadata without exposing session credentials.

Signature

declare const publishSelection: (
  stream: ObservabilityStream,
  previous: InspectorSelection,
  next: InspectorSelection,
) => void;

Source

options.ts

Parses trusted tool launch flags without importing an application’s config or dependencies.

INSPECTOR_HELP

Public standalone launch help; tokens are accepted only through private files.

Signature

declare const INSPECTOR_HELP: "Usage: relkit-inspector [options]\n  --project-root <directory>     Discover running sessions without evaluating the project\n  --connection-file <file>       Explicitly select one private session descriptor\n  --credential-file <file>       Private descriptor supplying matching session credentials\n  --target <http-origin>         Override network routing while verifying original identity\n  --history-directory <path>     Persistent project-bound history (default .relkit/observability)\n  --hostname <host>              UI bind host (default 127.0.0.1)\n  --port <number>                UI port (default 3210)\n  --help                        Show this help\n";

Source

parseInspectorOptions

Validates all launch authority before opening a listener, history or a child.

Signature

declare const parseInspectorOptions: (args: readonly string[]) => InspectorOptions;

Source

options.types.ts

Trusted launch inputs; none are accepted from a browser request.

InspectorOptions (interface)

Trusted launch inputs; none are accepted from a browser request.

Signature

export interface InspectorOptions {
  readonly projectRoot?: string;
  readonly connectionFile?: string;
  readonly credentialFile?: string;
  readonly target?: string;
  readonly historyDirectory?: string;
  readonly hostname: string;
  readonly port: number;
}

Source

remote.service.ts

Authenticates bounded server-to-server requests without exposing app credentials to UI.

InspectorRemote (class)

Remote transport can be replaced by a deterministic Layer in collection tests.

Signature

declare class InspectorRemote

Source

InspectorRemoteLive

Live request capability; acquisition opens no network connections.

Signature

declare const InspectorRemoteLive: Layer.Layer<InspectorRemote, never, never>;

Source

remote.types.ts

Server-only remote authority with no application module evaluation.

InspectorRemoteOperations (interface)

Single-shot requests preserve native operation IDs; callers never retry mutations.

Signature

export interface InspectorRemoteOperations {
  readonly request: (
    connection: InspectionConnectionFile,
    path: string,
    options?: RequestInit,
    target?: string,
  ) => Effect.Effect<Response, InspectionConnectionError>;
  readonly json: (response: Response) => Effect.Effect<string, InspectionConnectionError>;
}

Source

tool-backend.ts

Protects UI server requests and serves history locally while forwarding live operations once.

inspectorBackend

The packaged Next server alone receives credentials for this local hop.

Signature

declare const inspectorBackend: (
  state: InspectorToolStateRef,
  remote: InspectorRemoteOperations,
  token: string,
  options: InspectorOptions,
  stream: ObservabilityStream,
) => (request: Request) => Effect.Effect<Response, never, never>;

Source

tool-history.ts

Keeps history acquisition attached to the tool and hides retiring writers before native cleanup.

acquireHistory

Opens legacy project history in a parent-owned child Scope and rejects cross-project reuse.

Signature

declare const acquireHistory: (
  state: InspectorToolStateRef,
  files: InspectionFilesOperations,
  options: InspectorOptions,
) => Effect.Effect<undefined, InspectionConnectionError, Scope.Scope | InspectorHistoryNative>;

Source

recoverInspection

Recovery detaches unavailable history and its connection fence before awaiting a slow close.

Signature

declare const recoverInspection: (
  state: InspectorToolStateRef,
  error: InspectionConnectionError,
) => Effect.Effect<void, never, never>;

Source

tool-loop.ts

Serializes bounded discovery, recovery and collection independently from application requests.

inspectionLoop

Only one poll/batch can be pending; support failure uses a finite recovery interval.

Signature

declare const inspectionLoop: (
  state: InspectorToolStateRef,
  discovery: InspectorDiscoveryOperations,
  remote: InspectorRemoteOperations,
  files: InspectionFilesOperations,
  options: InspectorOptions,
  stream: ObservabilityStream,
) => Effect.Effect<never, InspectionConnectionError, Scope | InspectorHistoryNative>;

Source

tool-main.ts

Shares the native signal owner between package and restricted container entries.

runInspectorMain

Signature

declare const runInspectorMain: (container: boolean) => void;

Source

tool-state.types.ts

Tool-owned projection; browser responses must select safe fields instead of serializing it.

InspectorHistoryOwner (interface)

One native writer and its child Scope survive app generation/session changes.

Signature

export interface InspectorHistoryOwner {
  readonly projectId: string;
  readonly scope: Scope.Closeable;
  readonly operations: InspectorHistoryOperations;
}

Source

InspectorToolState (interface)

Collection state contains only one finite batch at a time; no pending write queue.

Signature

export interface InspectorToolState {
  readonly selection: InspectorSelection;
  readonly history: InspectorHistoryOwner | undefined;
  readonly sessionId: string | undefined;
  readonly through: number;
  readonly error: string | undefined;
  readonly incomplete: boolean;
  readonly droppedRecords: number;
  readonly lossKey?: string | undefined;
  readonly producerFailed?: number | undefined;
  readonly producerDropped?: number | undefined;
}

Source

InspectorToolStateRef (type alias)

Shared projection is owned by the acquired tool, never module global.

Signature

type InspectorToolStateRef = Ref.Ref<InspectorToolState>;

Source

tool.service.ts

Composes standalone UI, collector, private discovery and a single project history writer.

InspectorTool (class)

Native authority is captured once; every run owns an independent tool Scope.

Signature

declare class InspectorTool

Source

InspectorToolLive

Live command composition; no app compiler, evaluator or native feature SDK is included.

Signature

declare const InspectorToolLive: Layer.Layer<InspectorTool, never, never>;

Source

ui-native.service.ts

Owns the packaged Node UI child without inheriting application environment values.

InspectorUiNative (class)

Native UI acquisition is separate from all application/session ownership.

Signature

declare class InspectorUiNative

Source

InspectorUiNativeLive

Live child adapter, acquired only by an explicit standalone launch.

Signature

declare const InspectorUiNativeLive: Layer.Layer<InspectorUiNative, never, never>;

Source

acquireInspectorUi

Runs the exact packaged UI and joins its process on tool exit.

Signature

declare const acquireInspectorUi: (
  entry: string,
  options: InspectorOptions,
  backend: string,
  token: string,
) => Effect.Effect<
  Effect.Effect<never, InspectionConnectionError, never>,
  InspectionConnectionError,
  Scope
>;

Source

ui-readiness.ts

Requires complete UI response bytes and joins cancellation before advertising listening.

probeInspectorUi

Fetch cancellation reaches both headers and body; an oversized UI reply is never ready.

Signature

declare const probeInspectorUi: (
  fetcher: typeof fetch,
  endpoint: string,
) => Effect.Effect<boolean, InspectionConnectionError, never>;

Source

waitInspectorUiReady

The caller supplies native authority; expected connection failures retry within one minute.

Signature

declare const waitInspectorUiReady: (
  probe: Effect.Effect<boolean, InspectionConnectionError>,
) => Effect.Effect<boolean, InspectionConnectionError, never>;

Source