@introspection-sdk/introspection-node 0.4.1 → 0.4.3

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,4 +1,19 @@
 import { DiagLogLevel, DiagLogger } from "@opentelemetry/api";
+import { HttpsProxyAgent } from "https-proxy-agent";
+
+function getHttpsProxyUrl(): string | undefined {
+  return process.env.HTTPS_PROXY || undefined;
+}
+
+export function withOtlpHttpsProxy<T extends object>(options: T): T {
+  const proxyUrl = getHttpsProxyUrl();
+  if (!proxyUrl) return options;
+
+  return {
+    ...options,
+    httpAgentOptions: () => new HttpsProxyAgent(proxyUrl),
+  } as T;
+}
 
 /**
  * Logger for introspection-sdk package.