@introspection-sdk/introspection-node 0.19.1 → 0.21.0

package/src/resources/experiments.ts

@@ -1,176 +0,0 @@
-import type {
-  Experiment,
-  ExperimentCreate,
-  ExperimentListParams,
-  ExperimentUpdate,
-  Paginated,
-  RunRequest,
-  RunnerSpec,
-  Uuid,
-} from "@introspection-sdk/types";
-import type { HttpClient } from "../http.js";
-import type { IntrospectionClient } from "../client.js";
-import { Paginator, cursorPaginate } from "../pagination.js";
-import { Runner, type RunnerSource } from "../runner.js";
-
-interface ExperimentRunRequestBody {
-  identity?: {
-    user_id?: string;
-    anonymous_id?: string;
-    conversation_id?: string;
-  };
-  caller?: RunRequest["caller"];
-  agent_name?: string;
-  ttl_seconds?: number;
-  scope?: string;
-}
-
-function toRunBody(opts?: RunRequest): ExperimentRunRequestBody | undefined {
-  if (!opts) return undefined;
-  const out: ExperimentRunRequestBody = {};
-  if (opts.identity) out.identity = opts.identity;
-  if (opts.caller) out.caller = opts.caller;
-  if (opts.agent_name !== undefined) out.agent_name = opts.agent_name;
-  if (opts.ttl_seconds !== undefined) out.ttl_seconds = opts.ttl_seconds;
-  if (opts.scope !== undefined) out.scope = opts.scope;
-  return out;
-}
-
-export class ExperimentsApi {
-  constructor(
-    private readonly http: HttpClient,
-    private readonly client: IntrospectionClient,
-  ) {}
-
-  /**
-   * List experiments matching `params`. `await` the result for the first
-   * page, or `for await` it to stream every experiment across pages
-   * (fetched lazily — `limit` sets the page size, `next` the starting
-   * cursor; stop early to stop fetching).
-   */
-  list(params: ExperimentListParams): Paginator<Experiment> {
-    return cursorPaginate(
-      (next) =>
-        this.http.request<Paginated<Experiment>>({
-          method: "GET",
-          path: "/v1/experiments",
-          query: { ...params, next } as unknown as Record<string, unknown>,
-        }),
-      params.next,
-    );
-  }
-
-  get(id: Uuid): Promise<Experiment> {
-    return this.http.request<Experiment>({
-      method: "GET",
-      path: `/v1/experiments/${encodeURIComponent(id)}`,
-    });
-  }
-
-  create(input: ExperimentCreate): Promise<Experiment> {
-    return this.http.request<Experiment>({
-      method: "POST",
-      path: "/v1/experiments",
-      body: input,
-    });
-  }
-
-  update(id: Uuid, input: ExperimentUpdate): Promise<Experiment> {
-    return this.http.request<Experiment>({
-      method: "PATCH",
-      path: `/v1/experiments/${encodeURIComponent(id)}`,
-      body: input,
-    });
-  }
-
-  delete(id: Uuid): Promise<void> {
-    return this.http.request<void>({
-      method: "DELETE",
-      path: `/v1/experiments/${encodeURIComponent(id)}`,
-      expect: "empty",
-    });
-  }
-
-  startById(id: Uuid): Promise<Experiment> {
-    return this.http.request<Experiment>({
-      method: "POST",
-      path: `/v1/experiments/${encodeURIComponent(id)}/start`,
-      body: {},
-    });
-  }
-
-  endById(id: Uuid): Promise<Experiment> {
-    return this.http.request<Experiment>({
-      method: "POST",
-      path: `/v1/experiments/${encodeURIComponent(id)}/end`,
-      body: {},
-    });
-  }
-
-  cancelById(id: Uuid): Promise<Experiment> {
-    return this.http.request<Experiment>({
-      method: "POST",
-      path: `/v1/experiments/${encodeURIComponent(id)}/cancel`,
-      body: {},
-    });
-  }
-
-  async runById(id: Uuid, opts?: RunRequest): Promise<Runner> {
-    const spec = await this.http.request<RunnerSpec>({
-      method: "POST",
-      path: `/v1/experiments/${encodeURIComponent(id)}/run`,
-      body: toRunBody(opts) ?? {},
-    });
-    const source: RunnerSource = {
-      kind: "experiment",
-      id,
-      options: opts,
-    };
-    return new Runner(this.client, source, spec);
-  }
-}
-
-export class ExperimentHandle {
-  constructor(
-    private readonly api: ExperimentsApi,
-    private readonly id: Uuid,
-  ) {}
-
-  run(opts?: RunRequest): Promise<Runner> {
-    return this.api.runById(this.id, opts);
-  }
-
-  start(): Promise<Experiment> {
-    return this.api.startById(this.id);
-  }
-
-  end(): Promise<Experiment> {
-    return this.api.endById(this.id);
-  }
-
-  cancel(): Promise<Experiment> {
-    return this.api.cancelById(this.id);
-  }
-}
-
-export type ExperimentHandleFactory = (id: Uuid) => ExperimentHandle;
-
-export function attachExperiments(
-  client: IntrospectionClient,
-  http: HttpClient,
-): ExperimentsApi & ExperimentHandleFactory {
-  const api = new ExperimentsApi(http, client);
-  const factory: ExperimentHandleFactory = (id: Uuid) =>
-    new ExperimentHandle(api, id);
-  const hybrid = factory as ExperimentsApi & ExperimentHandleFactory;
-  hybrid.list = api.list.bind(api);
-  hybrid.get = api.get.bind(api);
-  hybrid.create = api.create.bind(api);
-  hybrid.update = api.update.bind(api);
-  hybrid.delete = api.delete.bind(api);
-  hybrid.startById = api.startById.bind(api);
-  hybrid.endById = api.endById.bind(api);
-  hybrid.cancelById = api.cancelById.bind(api);
-  hybrid.runById = api.runById.bind(api);
-  return hybrid;
-}

package/src/resources/recipes.ts

@@ -1,74 +0,0 @@
-import type {
-  Paginated,
-  Recipe,
-  RecipeCreate,
-  RecipeListParams,
-  RecipeUpdate,
-  Uuid,
-} from "@introspection-sdk/types";
-import type { HttpClient } from "../http.js";
-import { Paginator, cursorPaginate } from "../pagination.js";
-
-/**
- * Programmatic CRUD for `/v1/recipes` on the CP.
- *
- * Recipes are immutable build artefacts (repository + git ref + commit
- * sha + optional sub-path). They are referenced by runtimes via
- * `runtime.recipe_id` and by experiment arms via `arm.recipe_id`.
- */
-export class RecipesApi {
-  constructor(private readonly http: HttpClient) {}
-
-  /**
-   * List recipes matching `params`. `await` the result for the first
-   * page, or `for await` it to stream every recipe across pages (fetched
-   * lazily — `limit` sets the page size, `next` the starting cursor; stop
-   * early to stop fetching).
-   */
-  list(params: RecipeListParams): Paginator<Recipe> {
-    return cursorPaginate(
-      (next) =>
-        this.http.request<Paginated<Recipe>>({
-          method: "GET",
-          path: "/v1/recipes",
-          query: { ...params, next } as unknown as Record<string, unknown>,
-        }),
-      params.next,
-    );
-  }
-
-  get(id: Uuid): Promise<Recipe> {
-    return this.http.request<Recipe>({
-      method: "GET",
-      path: `/v1/recipes/${encodeURIComponent(id)}`,
-    });
-  }
-
-  create(input: RecipeCreate): Promise<Recipe> {
-    return this.http.request<Recipe>({
-      method: "POST",
-      path: "/v1/recipes",
-      body: input,
-    });
-  }
-
-  update(id: Uuid, input: RecipeUpdate): Promise<Recipe> {
-    return this.http.request<Recipe>({
-      method: "PATCH",
-      path: `/v1/recipes/${encodeURIComponent(id)}`,
-      body: input,
-    });
-  }
-
-  delete(id: Uuid): Promise<void> {
-    return this.http.request<void>({
-      method: "DELETE",
-      path: `/v1/recipes/${encodeURIComponent(id)}`,
-      expect: "empty",
-    });
-  }
-}
-
-export function attachRecipes(http: HttpClient): RecipesApi {
-  return new RecipesApi(http);
-}

package/src/resources/runtimes.ts

@@ -1,31 +0,0 @@
-import {
-  RuntimeHandle,
-  RuntimesClient,
-  attachRuntimes as attachSharedRuntimes,
-  isUuid,
-  type RuntimeHandleFactory as SharedRuntimeHandleFactory,
-} from "@introspection-sdk/http";
-import type { HttpClient } from "../http.js";
-import type { IntrospectionClient } from "../client.js";
-import { Runner } from "../runner.js";
-
-export { RuntimeHandle, isUuid };
-
-export class RuntimesApi extends RuntimesClient<Runner> {
-  constructor(
-    http: HttpClient,
-    private readonly client: IntrospectionClient,
-  ) {
-    super(http, (source, spec) => new Runner(this.client, source, spec));
-  }
-}
-
-export type RuntimeHandleFactory = SharedRuntimeHandleFactory<Runner>;
-
-export function attachRuntimes(
-  client: IntrospectionClient,
-  http: HttpClient,
-): RuntimesApi & RuntimeHandleFactory {
-  const api = new RuntimesApi(http, client);
-  return attachSharedRuntimes(api) as RuntimesApi & RuntimeHandleFactory;
-}

package/src/runner.ts

@@ -1,213 +0,0 @@
-import {
-  RunnerExpiredError,
-  type RunnerContext,
-  type RunnerDeployment,
-  type RunnerSpec,
-  type RunRequest,
-  type Uuid,
-} from "@introspection-sdk/types";
-import {
-  ConversationsApi,
-  EventsApi,
-  FilesApi,
-  MetricsApi,
-  SharesApi,
-  TasksApi,
-} from "@introspection-sdk/http";
-import { HttpClient } from "./http.js";
-import type { IntrospectionClient } from "./client.js";
-
-/**
- * Where this Runner came from, so `refresh()` can call CP again with the
- * same arguments to obtain a fresh `RunnerSpec` (manual escape hatch only;
- * not auto-scheduled).
- */
-export type RunnerSource =
-  | { kind: "runtime"; id: Uuid; options?: RunRequest }
-  | { kind: "experiment"; id: Uuid; options?: RunRequest };
-
-/**
- * Live handle to a Data Plane sandbox. Holds the bearer JWT, the DP
- * endpoint URL, and the runtime/experiment context, and exposes the
- * runner-bound `tasks`, `files`, `conversations`, `events`, and
- * `metrics` namespaces (the telemetry reads are Data-Plane-scoped and so
- * hang off the runner, which carries the DP bearer + `events:read`).
- *
- * In v1 of the agent-session-based design, token refresh is handled
- * server-side by the DP materializer attached to the agent session — the
- * SDK does NOT auto-refresh and does NOT install a 401 safety-net. The
- * `refresh()` method is kept as a manual escape hatch that re-calls the
- * CP `/run` route to mint a brand-new spec.
- */
-export class Runner {
-  private spec: RunnerSpec;
-  private http: HttpClient;
-  private closed = false;
-
-  // Public API surfaces.
-  readonly tasks: TasksApi;
-  readonly files: FilesApi;
-  readonly conversations: ConversationsApi;
-  readonly events: EventsApi;
-  readonly metrics: MetricsApi;
-  readonly shares: SharesApi;
-
-  constructor(
-    private readonly client: IntrospectionClient,
-    private readonly source: RunnerSource,
-    spec: RunnerSpec,
-  ) {
-    this.spec = spec;
-    this.http = this.buildHttp();
-    this.tasks = new TasksApi(this.guardedHttp(this.http));
-    this.files = new FilesApi(this.guardedHttp(this.http));
-    this.conversations = new ConversationsApi(this.guardedHttp(this.http));
-    this.events = new EventsApi(this.guardedHttp(this.http));
-    this.metrics = new MetricsApi(this.guardedHttp(this.http));
-    this.shares = new SharesApi(this.guardedHttp(this.http));
-  }
-
-  // --- public accessors ---
-
-  /** DP REST base URL the runner is bound to. */
-  get dpEndpoint(): string {
-    return this.spec.deployment.endpoint;
-  }
-
-  /** Routing target — DP endpoint / slug / region. */
-  get deployment(): Readonly<RunnerDeployment> {
-    return Object.freeze({ ...this.spec.deployment });
-  }
-
-  /** Session lifetime (ISO-8601 string). */
-  get expires_at(): string {
-    return this.spec.expires_at;
-  }
-
-  /** Session ID assigned by CP. */
-  get session_id(): string {
-    return this.spec.session_id;
-  }
-
-  /** Resolved runtime / arm / recipe / identity / caller context. */
-  get context(): Readonly<RunnerContext> {
-    return Object.freeze({ ...this.spec.runtime_context });
-  }
-
-  /** True once `close()` has been called. */
-  get isClosed(): boolean {
-    return this.closed;
-  }
-
-  // --- lifecycle ---
-
-  /**
-   * Manual escape hatch: re-call CP `/v1/runtimes/{id}/run` or
-   * `/v1/experiments/{id}/run` with the original `RunRequest` and replace
-   * this runner's in-memory spec with a fresh one.
-   *
-   * Not auto-scheduled — in v1 the DP materializer refreshes the
-   * underlying access token transparently for the agent-session-backed
-   * runner. Call this only if you have an explicit reason to mint a new
-   * session (e.g. you held a runner across a very long pause).
-   */
-  async refresh(): Promise<void> {
-    if (this.closed) {
-      throw new RunnerExpiredError({
-        message: "Runner has been closed",
-        status: 401,
-        code: "runner_expired",
-      });
-    }
-    const fresh = await this.requestFreshSpec();
-    this.spec = fresh;
-    // Note: we intentionally don't swap the underlying `http` here — the
-    // constructor-time bindings stay stable for the lifetime of the Runner.
-    // Callers wanting a freshly-bound Runner should call
-    // `client.runtimes(id).run(...)` again.
-  }
-
-  /**
-   * Best-effort close — flips a local `isClosed` flag so subsequent
-   * `runner.tasks` / `runner.files` / `runner.conversations` calls
-   * throw a friendly error. No
-   * server-side revoke is performed; future work will route a revoke via
-   * the CP locator-token path.
-   */
-  async close(): Promise<void> {
-    this.closed = true;
-  }
-
-  // --- internals ---
-
-  private buildHttp(): HttpClient {
-    const advanced = this.client.advancedOptions;
-    return new HttpClient({
-      apiUrl: this.spec.deployment.endpoint,
-      token: this.spec.session_token,
-      additionalHeaders: advanced.additionalHeaders,
-      fetch: advanced.fetch,
-    });
-  }
-
-  /**
-   * Wrap an HttpClient so that calls after `close()` fail with a clear
-   * `RunnerExpiredError` instead of hitting the network with a stale
-   * bearer. No 401 retry / refresh logic — that is the DP materializer's
-   * job in v1.
-   */
-  private guardedHttp(http: HttpClient): HttpClient {
-    const proxy: HttpClient = Object.create(http);
-    proxy.request = async <T>(
-      opts: Parameters<HttpClient["request"]>[0],
-    ): Promise<T> => {
-      this.assertOpen();
-      return http.request<T>(opts);
-    };
-    proxy.stream = async (
-      opts: Parameters<HttpClient["stream"]>[0],
-    ): Promise<Response> => {
-      this.assertOpen();
-      return http.stream(opts);
-    };
-    return proxy;
-  }
-
-  private assertOpen(): void {
-    if (this.closed) {
-      throw new RunnerExpiredError({
-        message: "Runner has been closed",
-        status: 401,
-        code: "runner_expired",
-      });
-    }
-  }
-
-  private async requestFreshSpec(): Promise<RunnerSpec> {
-    const http = this.client.cpHttp;
-    const body = toRunBody(this.source.options);
-    if (this.source.kind === "runtime") {
-      return await http.request<RunnerSpec>({
-        method: "POST",
-        path: `/v1/runtimes/${encodeURIComponent(this.source.id)}/run`,
-        body,
-      });
-    }
-    return await http.request<RunnerSpec>({
-      method: "POST",
-      path: `/v1/experiments/${encodeURIComponent(this.source.id)}/run`,
-      body,
-    });
-  }
-}
-
-function toRunBody(opts?: RunRequest): Record<string, unknown> {
-  if (!opts) return {};
-  const out: Record<string, unknown> = {};
-  if (opts.identity) out.identity = opts.identity;
-  if (opts.caller) out.caller = opts.caller;
-  if (opts.agent_name !== undefined) out.agent_name = opts.agent_name;
-  if (opts.ttl_seconds !== undefined) out.ttl_seconds = opts.ttl_seconds;
-  if (opts.scope !== undefined) out.scope = opts.scope;
-  return out;
-}

package/src/types.ts

@@ -1,13 +0,0 @@
-/**
- * Re-export shared types and functions from @introspection-sdk/types
- */
-export type {
-  AdvancedOptions,
-  IntrospectionClientOptions,
-  FeedbackOptions,
-  UserTraits,
-} from "@introspection-sdk/types";
-
-export type { GenAiContext, IdentityContext } from "@introspection-sdk/types";
-
-export { generateEventId } from "@introspection-sdk/types";

package/src/utils.ts

@@ -1,95 +0,0 @@
-import { DiagLogLevel, DiagLogger } from "@opentelemetry/api";
-import { HttpsProxyAgent } from "https-proxy-agent";
-import { getProxyForUrl } from "proxy-from-env";
-
-/**
- * Attach a forward-proxy agent to OTLP exporter options when a proxy is
- * configured for the exporter's endpoint.
- *
- * The OTLP proto exporters use Node's `http`/`https` stack, so this uses
- * `HttpsProxyAgent` (an `http.Agent`) rather than the undici dispatcher from
- * `@introspection-sdk/introspection-proxy` — a dispatcher only applies to
- * `fetch`. Unlike undici's `EnvHttpProxyAgent`, `HttpsProxyAgent` ignores
- * `NO_PROXY`, so we resolve the proxy per-endpoint with `proxy-from-env`'s
- * {@link getProxyForUrl}, which returns `""` when the host matches `NO_PROXY`.
- * This keeps in-cluster endpoints (e.g. `*.svc.cluster.local`) on a direct
- * connection instead of tunnelling them through the egress proxy, which has no
- * route for them.
- */
-export function withOtlpHttpsProxy<T extends { url?: string }>(options: T): T {
-  const proxyUrl = options.url ? getProxyForUrl(options.url) : "";
-  if (!proxyUrl) return options;
-
-  return {
-    ...options,
-    httpAgentOptions: () => new HttpsProxyAgent(proxyUrl),
-  } as T;
-}
-
-/**
- * Logger for introspection-sdk package.
- * Uses OpenTelemetry's diagnostic logger.
- */
-class IntrospectionLogger implements DiagLogger {
-  private logLevel: DiagLogLevel;
-
-  constructor() {
-    const logLevelStr = (
-      process.env.INTROSPECTION_LOG_LEVEL || "INFO"
-    ).toUpperCase();
-    this.logLevel = this.parseLogLevel(logLevelStr);
-  }
-
-  private parseLogLevel(level: string): DiagLogLevel {
-    switch (level) {
-      case "ERROR":
-        return DiagLogLevel.ERROR;
-      case "WARN":
-        return DiagLogLevel.WARN;
-      case "INFO":
-        return DiagLogLevel.INFO;
-      case "DEBUG":
-        return DiagLogLevel.DEBUG;
-      case "VERBOSE":
-        return DiagLogLevel.VERBOSE;
-      default:
-        return DiagLogLevel.INFO;
-    }
-  }
-
-  private shouldLog(level: DiagLogLevel): boolean {
-    return level <= this.logLevel;
-  }
-
-  error(...args: unknown[]): void {
-    if (this.shouldLog(DiagLogLevel.ERROR)) {
-      console.error("[introspection-sdk]", ...args);
-    }
-  }
-
-  warn(...args: unknown[]): void {
-    if (this.shouldLog(DiagLogLevel.WARN)) {
-      console.warn("[introspection-sdk]", ...args);
-    }
-  }
-
-  info(...args: unknown[]): void {
-    if (this.shouldLog(DiagLogLevel.INFO)) {
-      console.info("[introspection-sdk]", ...args);
-    }
-  }
-
-  debug(...args: unknown[]): void {
-    if (this.shouldLog(DiagLogLevel.DEBUG)) {
-      console.debug("[introspection-sdk]", ...args);
-    }
-  }
-
-  verbose(...args: unknown[]): void {
-    if (this.shouldLog(DiagLogLevel.VERBOSE)) {
-      console.debug("[introspection-sdk]", ...args);
-    }
-  }
-}
-
-export const logger = new IntrospectionLogger();

package/src/version.ts

@@ -1,2 +0,0 @@
-/** Version information for introspection-sdk package. */
-export const VERSION = "0.1.0";

package/tsconfig.json

@@ -1,8 +0,0 @@
-{
-  "extends": "@repo/typescript-config/react-library.json",
-  "compilerOptions": {
-    "outDir": "dist"
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "dist"]
-}