@introspection-sdk/introspection-browser 0.5.4 → 0.5.5

package/src/api/index.ts

@@ -11,18 +11,18 @@
  * import { IntrospectionApiClient } from "@introspection-sdk/introspection-browser/api";
  *
  * const client = new IntrospectionApiClient({
- *   dpUrl: "https://dp.us.introspection.dev",
+ *   cpUrl: "https://api.introspection.dev",
  *   // your backend mints the Introspection access token (the session's
  *   // project is derived from its claims — no projectId option needed)
  *   getToken: () => fetch("/api/introspection/token").then((r) => r.text()),
  * });
  *
- * await client.connect(); // → intro_dp_session cookie
- * const run = await client.tasks.start({
- *   prompt: "Summarize my latest order",
- *   agent_name: "support-agent",
+ * const runner = await client.runtimes("support-agent").run({
  *   identity: { user_id: "u_42" },
  * });
+ * const run = await runner.tasks.start({
+ *   prompt: "Summarize my latest order",
+ * });
  * for await (const ev of run.stream()) console.log(ev.event, ev.data);
  * ```
  */
@@ -31,6 +31,20 @@ export {
   IntrospectionApiClient,
   type IntrospectionApiClientOptions,
 } from "./client.js";
+export {
+  BrowserRunner,
+  Runner,
+  type BrowserRunnerOwner,
+  type BrowserRunnerSource,
+} from "./runner.js";
+export {
+  BrowserRuntimesClient,
+  BrowserRuntimeHandle,
+  attachBrowserRuntimes,
+  isUuid,
+  type BrowserRuntimeHandleFactory,
+  type BrowserRuntimeRunRequestBody,
+} from "./runtimes.js";
 export {
   TasksClient,
   TaskRunsClient,
@@ -39,16 +53,20 @@ export {
   type StartTaskParams,
 } from "./tasks.js";
 export {
-  FilesClient,
+  ConversationItemsClient,
+  ConversationsClient,
   FileVersionsClient,
+  FilesClient,
+  SharesClient,
   type FileUploadBody,
-} from "./files.js";
+} from "@introspection-sdk/http";
 export {
-  ConversationsClient,
-  ConversationItemsClient,
-} from "./conversations.js";
-export { SharesClient } from "./shares.js";
-export { BrowserHttpClient, type BrowserHttpConfig } from "./http.js";
+  BrowserBearerHttpClient,
+  BrowserHttpClient,
+  type BrowserApiHttpClient,
+  type BrowserBearerHttpConfig,
+  type BrowserHttpConfig,
+} from "./http.js";
 export { parseSse } from "./sse.js";
 export {
   Paginator,
@@ -86,6 +104,15 @@ export type {
   ShareResourceType,
   ShareCreateParams,
   ShareListParams,
+  Recipe,
+  RunRequest,
+  RunnerContext,
+  RunnerDeployment,
+  RunnerSpec,
+  Runtime,
+  RuntimeCreate,
+  RuntimeListParams,
+  RuntimeUpdate,
 } from "@introspection-sdk/types";
 export {
   IntrospectionAPIError,
@@ -93,4 +120,5 @@ export {
   InsufficientScopeError,
   NotFoundError,
   NetworkError,
+  RunnerExpiredError,
 } from "@introspection-sdk/types";

package/src/api/runner.ts

@@ -0,0 +1,127 @@
+import {
+  RunnerExpiredError,
+  type RunnerContext,
+  type RunnerDeployment,
+  type RunnerSpec,
+  type RunRequest,
+  type Uuid,
+} from "@introspection-sdk/types";
+import {
+  ConversationsClient,
+  FilesClient,
+  SharesClient,
+  TasksClient,
+} from "@introspection-sdk/http";
+import { BrowserBearerHttpClient } from "./http.js";
+
+export type BrowserRunnerSource =
+  | { kind: "runtime"; id: Uuid; options?: RunRequest }
+  | { kind: "experiment"; id: Uuid; options?: RunRequest };
+
+export interface BrowserRunnerOwner {
+  readonly additionalHeaders?: Record<string, string>;
+  readonly fetch?: typeof fetch;
+  requestFreshRunnerSpec(source: BrowserRunnerSource): Promise<RunnerSpec>;
+}
+
+/**
+ * Browser-side live handle to a Data Plane runner. Mirrors the Node Runner
+ * shape but uses browser-safe fetch transport and CP-minted bearer tokens.
+ */
+export class BrowserRunner {
+  private spec: RunnerSpec;
+  private http: BrowserBearerHttpClient;
+  private closed = false;
+
+  readonly tasks: TasksClient;
+  readonly files: FilesClient;
+  readonly conversations: ConversationsClient;
+  readonly shares: SharesClient;
+
+  constructor(
+    private readonly owner: BrowserRunnerOwner,
+    private readonly source: BrowserRunnerSource,
+    spec: RunnerSpec,
+  ) {
+    this.spec = spec;
+    this.http = this.buildHttp(spec);
+    const guarded = this.guardedHttp();
+    this.tasks = new TasksClient(guarded);
+    this.files = new FilesClient(guarded);
+    this.conversations = new ConversationsClient(guarded);
+    this.shares = new SharesClient(guarded);
+  }
+
+  get dpEndpoint(): string {
+    return this.spec.deployment.endpoint;
+  }
+
+  get deployment(): Readonly<RunnerDeployment> {
+    return Object.freeze({ ...this.spec.deployment });
+  }
+
+  get expires_at(): string {
+    return this.spec.expires_at;
+  }
+
+  get session_id(): string {
+    return this.spec.session_id;
+  }
+
+  get context(): Readonly<RunnerContext> {
+    return Object.freeze({ ...this.spec.runtime_context });
+  }
+
+  get isClosed(): boolean {
+    return this.closed;
+  }
+
+  async refresh(): Promise<void> {
+    this.assertOpen();
+    const fresh = await this.owner.requestFreshRunnerSpec(this.source);
+    this.spec = fresh;
+    this.http = this.buildHttp(fresh);
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+  }
+
+  private buildHttp(spec: RunnerSpec): BrowserBearerHttpClient {
+    return new BrowserBearerHttpClient({
+      apiUrl: spec.deployment.endpoint,
+      token: spec.session_token,
+      additionalHeaders: this.owner.additionalHeaders,
+      fetch: this.owner.fetch,
+    });
+  }
+
+  private guardedHttp(): BrowserBearerHttpClient {
+    const proxy: BrowserBearerHttpClient = Object.create(this.http);
+    proxy.request = async <T>(
+      opts: Parameters<BrowserBearerHttpClient["request"]>[0],
+    ): Promise<T> => {
+      this.assertOpen();
+      return this.http.request<T>(opts);
+    };
+    proxy.stream = async (
+      opts: Parameters<BrowserBearerHttpClient["stream"]>[0],
+    ): Promise<Response> => {
+      this.assertOpen();
+      return this.http.stream(opts);
+    };
+    return proxy;
+  }
+
+  private assertOpen(): void {
+    if (this.closed) {
+      throw new RunnerExpiredError({
+        message: "Runner has been closed",
+        status: 401,
+        code: "runner_expired",
+      });
+    }
+  }
+}
+
+export { BrowserRunner as Runner };

package/src/api/runtimes.ts

@@ -0,0 +1,32 @@
+import {
+  RuntimeHandle,
+  RuntimesClient,
+  attachRuntimes,
+  isUuid,
+  type RuntimeHandleFactory,
+  type RuntimeRunRequestBody,
+} from "@introspection-sdk/http";
+import type { BrowserApiHttpClient } from "./http.js";
+import { BrowserRunner, type BrowserRunnerOwner } from "./runner.js";
+
+export { isUuid };
+export type { RuntimeRunRequestBody as BrowserRuntimeRunRequestBody };
+
+export class BrowserRuntimesClient extends RuntimesClient<BrowserRunner> {
+  constructor(http: BrowserApiHttpClient, owner: BrowserRunnerOwner) {
+    super(http, (source, spec) => new BrowserRunner(owner, source, spec));
+  }
+}
+
+export { RuntimeHandle as BrowserRuntimeHandle };
+
+export type BrowserRuntimeHandleFactory = RuntimeHandleFactory<BrowserRunner>;
+
+export function attachBrowserRuntimes(
+  http: BrowserApiHttpClient,
+  owner: BrowserRunnerOwner,
+): BrowserRuntimesClient & BrowserRuntimeHandleFactory {
+  const api = new BrowserRuntimesClient(http, owner);
+  return attachRuntimes(api) as BrowserRuntimesClient &
+    BrowserRuntimeHandleFactory;
+}

package/src/api/tasks.ts

@@ -1,19 +1,10 @@
-import type {
-  Paginated,
-  RunIdentityInput,
-  SseEvent,
-  Task,
-  TaskCancelResponse,
-  TaskCreateResponse,
-  TaskListParams,
-  TaskRun,
-  TaskRunCreateParams,
-  TaskRunResponse,
-  TaskUpdateParams,
-} from "@introspection-sdk/types";
-import { Paginator, cursorPaginate } from "@introspection-sdk/http";
-import { BrowserHttpClient } from "./http.js";
-import { parseSse } from "./sse.js";
+import type { RunIdentityInput } from "@introspection-sdk/types";
+import {
+  RunHandle,
+  TaskRunsClient,
+  TasksClient as SharedTasksClient,
+  type ResourceHttpClient,
+} from "@introspection-sdk/http";
 
 /**
  * Body for creating a task directly against the DP from the browser.
@@ -65,149 +56,18 @@ function toTaskBody(params: CreateTaskParams): Record<string, unknown> {
   return body;
 }
 
-/** Live handle on a task's run: stream its events, collect text, cancel. */
-export class RunHandle {
-  constructor(
-    public readonly task: Task | null,
-    public readonly run: TaskRun,
-    private readonly runs: TaskRunsClient,
-  ) {}
-
-  stream(): AsyncIterable<SseEvent> {
-    return this.runs.stream(this.run.task_id, this.run.id);
-  }
-
-  cancel(): Promise<TaskCancelResponse> {
-    return this.runs.cancel(this.run.task_id, this.run.id);
-  }
-
-  /** Convenience: concatenate `data` from `text`/`message` SSE frames. */
-  async text(): Promise<string> {
-    let out = "";
-    for await (const ev of this.stream()) {
-      if (ev.event === "text" || ev.event === "message") out += ev.data;
-    }
-    return out;
-  }
-}
-
-export class TaskRunsClient {
-  constructor(private readonly http: BrowserHttpClient) {}
-
-  async create(taskId: string, body: TaskRunCreateParams): Promise<RunHandle> {
-    const res = await this.http.request<TaskRunResponse>({
-      method: "POST",
-      path: `/v1/tasks/${encodeURIComponent(taskId)}/runs`,
-      body,
-    });
-    return new RunHandle(null, res.run, this);
-  }
-
-  get(taskId: string, runId: string): Promise<TaskRun> {
-    return this.http.request<TaskRun>({
-      method: "GET",
-      path: `/v1/tasks/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(runId)}`,
-    });
-  }
-
-  cancel(taskId: string, runId: string): Promise<TaskCancelResponse> {
-    return this.http.request<TaskCancelResponse>({
-      method: "POST",
-      path: `/v1/tasks/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(runId)}/cancel`,
-    });
-  }
-
-  async *stream(taskId: string, runId: string): AsyncIterable<SseEvent> {
-    const res = await this.http.stream({
-      path: `/v1/tasks/${encodeURIComponent(taskId)}/runs/${encodeURIComponent(runId)}/stream`,
-    });
-    yield* parseSse(res);
-  }
-}
-
 /**
- * Cookie-authenticated `/v1/tasks` client. Mirrors the Node SDK's
- * `TasksApi` shape but is bound to a DP session cookie rather than a
- * bearer token, and lets the caller select the agent on create.
+ * Cookie-authenticated `/v1/tasks` client. The implementation is shared with
+ * Node's runner-bound task client; this browser subclass only adds the
+ * `identity -> metadata.identity` body mapping used by cookie-session calls.
  */
-export class TasksClient {
-  readonly runs: TaskRunsClient;
-
-  constructor(private readonly http: BrowserHttpClient) {
-    this.runs = new TaskRunsClient(http);
-  }
-
-  /**
-   * Tasks matching `params`. `await` it for the first page (preserving
-   * the wire envelope's counts + `next` cursor), or `for await` it to
-   * stream every task across pages (fetched lazily — `limit` sets the
-   * page size, `next` the starting cursor; stop early to stop fetching).
-   *
-   * Mirrors the Node SDK's `TasksApi.list`, which is the source of truth
-   * for the `/v1/tasks` shape.
-   */
-  list(params?: TaskListParams): Paginator<Task> {
-    return cursorPaginate(
-      (next) =>
-        this.http.request<Paginated<Task>>({
-          method: "GET",
-          path: "/v1/tasks",
-          query: { ...params, next } as Record<string, unknown>,
-        }),
-      params?.next,
-    );
-  }
-
-  create(body: CreateTaskParams): Promise<TaskCreateResponse> {
-    return this.http.request<TaskCreateResponse>({
-      method: "POST",
-      path: "/v1/tasks",
-      body: toTaskBody(body),
-    });
-  }
-
-  get(taskId: string): Promise<Task> {
-    return this.http.request<Task>({
-      method: "GET",
-      path: `/v1/tasks/${encodeURIComponent(taskId)}`,
-    });
-  }
-
-  update(taskId: string, body: TaskUpdateParams): Promise<Task> {
-    return this.http.request<Task>({
-      method: "PATCH",
-      path: `/v1/tasks/${encodeURIComponent(taskId)}`,
-      body,
-    });
-  }
-
-  delete(taskId: string): Promise<void> {
-    return this.http.request<void>({
-      method: "DELETE",
-      path: `/v1/tasks/${encodeURIComponent(taskId)}`,
-      expect: "empty",
-    });
-  }
-
-  archive(taskId: string): Promise<void> {
-    return this.http.request<void>({
-      method: "POST",
-      path: `/v1/tasks/${encodeURIComponent(taskId)}/archive`,
-      expect: "empty",
-    });
-  }
-
-  unarchive(taskId: string): Promise<void> {
-    return this.http.request<void>({
-      method: "POST",
-      path: `/v1/tasks/${encodeURIComponent(taskId)}/unarchive`,
-      expect: "empty",
-    });
-  }
-
-  /** Sugar: create a task + return a handle on its initial run. */
-  async start(params: StartTaskParams): Promise<RunHandle> {
-    const res = await this.create(params);
-    return new RunHandle(res.task, res.run, this.runs);
+export class TasksClient extends SharedTasksClient<
+  CreateTaskParams,
+  StartTaskParams
+> {
+  constructor(http: ResourceHttpClient) {
+    super(http, toTaskBody);
   }
 }
+
+export { RunHandle, TaskRunsClient };

package/dist/api/conversations.d.ts

@@ -1,84 +0,0 @@
-/**
- * Cookie-authenticated, read-only Conversations client for the browser
- * (`/v1/conversations`).
- *
- * Mirrors the Node SDK's runner-bound `ConversationsApi`, but rides the
- * DP `intro_dp_session` cookie via {@link BrowserHttpClient} instead of a
- * bearer token — so a single-page app reads conversation history with the
- * same identity session it uses for tasks and files. Conversations are a
- * projection over the immutable telemetry store: list summaries, walk a
- * conversation's items, or `retrieve()` the resolved state of one turn.
- */
-import type { ConversationItem, ConversationItemInclude, ConversationItemList, ConversationItemListParams, ConversationListParams, ConversationResponse, ConversationSummary } from "@introspection-sdk/types";
-import { Paginator } from "@introspection-sdk/http";
-import { BrowserHttpClient } from "./http.js";
-/**
- * Items of a conversation (`/v1/conversations/{id}/items`). Read-only.
- *
- * Paging is OpenAI-style underneath: the envelope has NO `next` token —
- * `list()` drives `after` = the previous page's `last_id` while
- * `has_more` is true.
- */
-export declare class ConversationItemsClient {
-    private readonly http;
-    constructor(http: BrowserHttpClient);
-    /**
-     * List items of a conversation. `await` the result for the first page
-     * (an OpenAI-style {@link ConversationItemList} envelope), or
-     * `for await` it to stream every item across pages (fetched lazily —
-     * `limit` sets the page size, `after` the starting cursor; stop early to
-     * stop fetching). Pass `order: "asc"` to walk the transcript from the
-     * start.
-     *
-     * Items carry the turn-local delta in `input_messages` — only the
-     * messages new to that turn. Use `get()` for the full input history.
-     */
-    list(conversationId: string, params?: ConversationItemListParams): Paginator<ConversationItem, ConversationItemList>;
-    /**
-     * Fetch a single conversation item. Unlike the list route, the
-     * detail's `input_messages` is the FULL input history for that span.
-     */
-    get(conversationId: string, itemId: string, params?: {
-        include?: ConversationItemInclude[];
-    }): Promise<ConversationItem>;
-}
-/**
- * Read-only Conversations client (`/v1/conversations`).
- *
- * Both `list()` and `items.list()` are auto-paging, but they drive
- * different wire protocols underneath: `list()` walks the standard
- * Introspection cursor envelope's opaque `next` token, while
- * `items.list()` walks an OpenAI-style envelope via `after` = the
- * previous page's `last_id` while `has_more` is true.
- */
-export declare class ConversationsClient {
-    private readonly http;
-    /** Items of a conversation — `conversations.items.list(...)` etc. */
-    readonly items: ConversationItemsClient;
-    constructor(http: BrowserHttpClient);
-    /**
-     * List conversation summaries matching `params`. `await` the result for
-     * the first page, or `for await` it to stream every summary across
-     * pages (fetched lazily — `limit` sets the page size, `next` the
-     * starting cursor; stop early to stop fetching).
-     */
-    list(params?: ConversationListParams): Paginator<ConversationSummary>;
-    /**
-     * Responses-API-style retrieve: load the state of a conversation as of
-     * one item — the full input history, output, system instructions, and
-     * tool definitions of that turn.
-     *
-     * When `itemId` is omitted, the latest LLM turn is used: the first
-     * item (in descending order) whose `node_type` is `"assistant"` or
-     * whose `operation_name` is `"chat"`, falling back to the first item
-     * with a non-null `output_message`. Returns `null` when the
-     * conversation has no items.
-     *
-     * For the full per-turn transcript instead, iterate
-     * `items.list(conversationId, { order: "asc" })`.
-     */
-    retrieve(conversationId: string, itemId?: string): Promise<ConversationResponse | null>;
-    /** Scan items in descending order for the most recent LLM turn. */
-    private findLatestTurnId;
-}
-//# sourceMappingURL=conversations.d.ts.map

package/dist/api/conversations.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"conversations.d.ts","sourceRoot":"","sources":["../../src/api/conversations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EAIpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,SAAS,EAAkB,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAS9C;;;;;;GAMG;AACH,qBAAa,uBAAuB;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,iBAAiB;IAEpD;;;;;;;;;;OAUG;IACH,IAAI,CACF,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,0BAA0B,GAClC,SAAS,CAAC,gBAAgB,EAAE,oBAAoB,CAAC;IAiBpD;;;OAGG;IACH,GAAG,CACD,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,uBAAuB,EAAE,CAAA;KAAE,GAC/C,OAAO,CAAC,gBAAgB,CAAC;CAO7B;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAmB;IAIlB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,uBAAuB,CAAC;gBAEX,IAAI,EAAE,iBAAiB;IAIpD;;;;;OAKG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC,mBAAmB,CAAC;IAYrE;;;;;;;;;;;;;OAaG;IACG,QAAQ,CACZ,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA6BvC,mEAAmE;YACrD,gBAAgB;CAc/B"}