@introspection-sdk/introspection-node 0.4.2 → 0.4.4

package/src/runner.ts

@@ -0,0 +1,194 @@
+import {
+  RunnerExpiredError,
+  type RunnerContext,
+  type RunnerDeployment,
+  type RunnerSpec,
+  type RunRequest,
+  type Uuid,
+} from "@introspection-sdk/types";
+import { HttpClient } from "./http.js";
+import { TasksApi } from "./runner-resources/tasks.js";
+import { FilesApi } from "./runner-resources/files.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` and `files` namespaces.
+ *
+ * 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;
+
+  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));
+  }
+
+  // --- 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` 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.ttl_seconds !== undefined) out.ttl_seconds = opts.ttl_seconds;
+  return out;
+}

package/src/streaming.ts

@@ -0,0 +1,57 @@
+import type { SseEvent } from "@introspection-sdk/types";
+
+/**
+ * Parse a `text/event-stream` Response into an async-iterable of SSE
+ * events. Minimal parser: handles `event:`, `data:` (multi-line),
+ * `id:`, `retry:`; ignores comments and unknown fields.
+ */
+export async function* parseSse(res: Response): AsyncIterable<SseEvent> {
+  if (!res.body) return;
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  let event = "message";
+  let data: string[] = [];
+  let id: string | undefined;
+  let retry: number | undefined;
+  const flush = (): SseEvent | null => {
+    if (data.length === 0 && event === "message" && id === undefined)
+      return null;
+    const ev: SseEvent = { event, data: data.join("\n") };
+    if (id !== undefined) ev.id = id;
+    if (retry !== undefined) ev.retry = retry;
+    event = "message";
+    data = [];
+    id = undefined;
+    retry = undefined;
+    return ev;
+  };
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    let nl: number;
+    while ((nl = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, nl).replace(/\r$/, "");
+      buf = buf.slice(nl + 1);
+      if (line === "") {
+        const ev = flush();
+        if (ev) yield ev;
+        continue;
+      }
+      if (line.startsWith(":")) continue;
+      const colon = line.indexOf(":");
+      const field = colon < 0 ? line : line.slice(0, colon);
+      const valueRaw = colon < 0 ? "" : line.slice(colon + 1).replace(/^ /, "");
+      if (field === "event") event = valueRaw;
+      else if (field === "data") data.push(valueRaw);
+      else if (field === "id") id = valueRaw;
+      else if (field === "retry") {
+        const n = Number(valueRaw);
+        if (Number.isFinite(n)) retry = n;
+      }
+    }
+  }
+  const ev = flush();
+  if (ev) yield ev;
+}

package/src/utils.ts

@@ -1,12 +1,19 @@
 import { DiagLogLevel, DiagLogger } from "@opentelemetry/api";
 import { HttpsProxyAgent } from "https-proxy-agent";
+import { resolveForwardProxyUrl } from "@introspection-sdk/introspection-proxy";
 
-function getHttpsProxyUrl(): string | undefined {
-  return process.env.HTTPS_PROXY || undefined;
-}
-
+/**
+ * Attach a forward-proxy agent to OTLP exporter options when a proxy is
+ * configured in the environment.
+ *
+ * Note: the OTLP proto exporters use Node's `http`/`https` stack, so this uses
+ * `HttpsProxyAgent` (an `http.Agent`) rather than the undici dispatcher from
+ * `./proxy.js` — a dispatcher only applies to `fetch`. The proxy *URL* is
+ * resolved by the shared {@link resolveForwardProxyUrl} so fetch and OTLP
+ * traffic agree on which proxy to use.
+ */
 export function withOtlpHttpsProxy<T extends object>(options: T): T {
-  const proxyUrl = getHttpsProxyUrl();
+  const proxyUrl = resolveForwardProxyUrl();
   if (!proxyUrl) return options;
 
   return {

package/dist/ai-sdk-integration.d.ts

@@ -1,123 +0,0 @@
-/**
- * AI SDK TelemetryIntegration for Introspection.
- *
- * Implements the Vercel AI SDK's TelemetryIntegration interface to capture
- * LLM interactions and export them as OpenTelemetry spans with gen_ai.*
- * semantic convention attributes to the Introspection backend.
- *
- * Similar to IntrospectionTracingProcessor for OpenAI Agents SDK and
- * IntrospectionClaudeHooks for Claude Agent SDK.
- *
- * @example
- * ```ts
- * import { IntrospectionAISDKIntegration } from "@introspection-sdk/introspection-node";
- * import { generateText } from "ai";
- * import { openai } from "@ai-sdk/openai";
- *
- * const introspection = new IntrospectionAISDKIntegration({
- *   token: "sk-intro-...",
- *   serviceName: "my-app",
- * });
- *
- * const { text } = await generateText({
- *   model: openai("gpt-4o"),
- *   prompt: "Hello!",
- *   experimental_telemetry: {
- *     isEnabled: true,
- *     integrations: [introspection],
- *   },
- * });
- *
- * await introspection.shutdown();
- * ```
- */
-import { type SpanExporter, type IdGenerator } from "@opentelemetry/sdk-trace-base";
-/** Advanced options for testing and customization. */
-export interface AISDKIntegrationAdvancedOptions {
-    /** Custom span exporter (for testing — use InMemorySpanExporter). */
-    spanExporter?: SpanExporter;
-    /** Custom ID generator (for testing). */
-    idGenerator?: IdGenerator;
-    /** Use SimpleSpanProcessor instead of BatchSpanProcessor (for testing). */
-    useSimpleSpanProcessor?: boolean;
-    /** Maximum batch size for span export. */
-    maxExportBatchSize?: number;
-    /** Delay between batch exports in milliseconds. */
-    scheduledDelayMillis?: number;
-}
-/** Configuration for {@link IntrospectionAISDKIntegration}. */
-export interface IntrospectionAISDKIntegrationOptions {
-    /** Authentication token (env: INTROSPECTION_TOKEN). */
-    token?: string;
-    /** Base URL for the API (env: INTROSPECTION_BASE_URL, default: "https://otel.introspection.dev"). */
-    baseUrl?: string;
-    /** Service name for telemetry (env: INTROSPECTION_SERVICE_NAME). */
-    serviceName?: string;
-    /** Additional headers to include in requests. */
-    additionalHeaders?: Record<string, string>;
-    /** Advanced options for testing and customization. */
-    advanced?: AISDKIntegrationAdvancedOptions;
-}
-/**
- * AI SDK {@link TelemetryIntegration} that captures LLM interactions and
- * exports them as OpenTelemetry spans with `gen_ai.*` semantic convention
- * attributes to the Introspection backend.
- *
- * Creates its own {@link BasicTracerProvider} — no external OTel setup required.
- * Each generation (generateText/streamText call) produces:
- * - A root span grouping the entire operation
- * - Step spans (one per LLM call) with full gen_ai attributes
- * - Tool call spans nested under their parent step
- */
-export declare class IntrospectionAISDKIntegration {
-    private _tracerProvider;
-    private _tracer;
-    private _generation;
-    constructor(options?: IntrospectionAISDKIntegrationOptions);
-    /**
-     * Called when a generation operation begins (before any LLM calls).
-     * Creates a root span to group all steps in this generation.
-     */
-    onStart: (event: unknown) => void;
-    /**
-     * Called when a step (individual LLM call) begins.
-     * Creates a child span under the root span and captures input messages.
-     */
-    onStepStart: (event: unknown) => void;
-    /**
-     * Called when a tool execution begins.
-     * Creates a child span under the current step span.
-     */
-    onToolCallStart: (event: unknown) => void;
-    /**
-     * Called when a tool execution completes.
-     * Sets output/error attributes and ends the tool span.
-     */
-    onToolCallFinish: (event: unknown) => void;
-    /**
-     * Called when a step (LLM call) completes.
-     * Sets gen_ai attributes (input/output messages, usage, model) and ends
-     * the step span.
-     */
-    onStepFinish: (event: unknown) => void;
-    /**
-     * Called when the entire generation completes (all steps finished).
-     * Sets total usage on the root span and ends it.
-     */
-    onFinish: (event: unknown) => void;
-    /**
-     * Shut down the tracer provider, flushing all pending spans.
-     *
-     * @returns A promise that resolves once shutdown is complete.
-     */
-    shutdown(): Promise<void>;
-    /**
-     * Force-flush any buffered spans to the Introspection backend.
-     *
-     * @returns A promise that resolves once the flush completes.
-     */
-    forceFlush(): Promise<void>;
-    /** Cleanly end any active generation, closing all open spans. */
-    private _endGeneration;
-}
-//# sourceMappingURL=ai-sdk-integration.d.ts.map

package/dist/ai-sdk-integration.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ai-sdk-integration.d.ts","sourceRoot":"","sources":["../src/ai-sdk-integration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAOH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAC;AAoBvC,sDAAsD;AACtD,MAAM,WAAW,+BAA+B;IAC9C,qEAAqE;IACrE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,yCAAyC;IACzC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,2EAA2E;IAC3E,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,0CAA0C;IAC1C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,+DAA+D;AAC/D,MAAM,WAAW,oCAAoC;IACnD,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qGAAqG;IACrG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,sDAAsD;IACtD,QAAQ,CAAC,EAAE,+BAA+B,CAAC;CAC5C;AAoBD;;;;;;;;;;GAUG;AACH,qBAAa,6BAA6B;IACxC,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,OAAO,CAA+C;IAC9D,OAAO,CAAC,WAAW,CAAgC;gBAEvC,OAAO,GAAE,oCAAyC;IA8F9D;;;OAGG;IACH,OAAO,GAAI,OAAO,OAAO,KAAG,IAAI,CA2D9B;IAEF;;;OAGG;IACH,WAAW,GAAI,OAAO,OAAO,KAAG,IAAI,CAgFlC;IAEF;;;OAGG;IACH,eAAe,GAAI,OAAO,OAAO,KAAG,IAAI,CA0CtC;IAEF;;;OAGG;IACH,gBAAgB,GAAI,OAAO,OAAO,KAAG,IAAI,CAgDvC;IAEF;;;;OAIG;IACH,YAAY,GAAI,OAAO,OAAO,KAAG,IAAI,CAuHnC;IAEF;;;OAGG;IACH,QAAQ,GAAI,OAAO,OAAO,KAAG,IAAI,CA+C/B;IAMF;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/B;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC,iEAAiE;IACjE,OAAO,CAAC,cAAc;CASvB"}