@oceanum/oceanumlab 4.6.0

package/src/chatRouter.ts

@@ -0,0 +1,329 @@
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { OCEANUM_AI_BACKEND_URL } from './constants';
+import type { Progress } from './progress';
+import { readSse } from './sse';
+import type { ObservedRun } from './notebookRun';
+import type { INotebookSnapshot } from './notebookContext';
+import { formatNotebookCells } from './notebookContext';
+
+/** One thing the backend asks us to place in the notebook. */
+export interface Block {
+  type: 'code' | 'markdown';
+  content: string;
+}
+
+/**
+ * What `/api/chat` answers with: one message, plus anything to place.
+ *
+ * This replaced a discriminated union of text/code/markdown responses
+ * (OCE-173). The union was exclusive, so the backend could not send a markdown
+ * table AND the query that produced it — it had to drop one. `message` is what
+ * goes in the chat window; `blocks` is what goes in the notebook, in order.
+ *
+ * `message` is always present now. On the old markdown variant it was optional,
+ * which is why the handoff used to fall back to 'Added markdown to notebook.'
+ */
+export interface OceanumResponse {
+  message: string;
+  blocks: Block[];
+}
+
+export interface ChatMessage {
+  role: 'user' | 'assistant';
+  content: string;
+}
+
+export interface RouteResult {
+  response: OceanumResponse;
+  hasCodeCellSelected: boolean;
+}
+
+export class ChatRouterError extends Error {
+  constructor(
+    message: string,
+    public readonly statusCode?: number
+  ) {
+    super(message);
+    this.name = 'ChatRouterError';
+  }
+}
+
+/**
+ * Check the body is the shape we expect before anything reads it.
+ *
+ * A bare `as OceanumResponse` cast used to be enough because the shape had not
+ * changed since the extension was written. It has now (OCE-173), and an
+ * extension pinned to one contract will meet a backend serving the other during
+ * any deploy where the two are not released together: the old body has no
+ * `blocks`, so `response.blocks.length` throws deep inside the handoff and the
+ * user sees nothing happen. One check turns that into the error the chat window
+ * already knows how to show.
+ */
+function asOceanumResponse(data: unknown): OceanumResponse {
+  const body = data as Partial<OceanumResponse> | null;
+  if (
+    !body ||
+    typeof body.message !== 'string' ||
+    !Array.isArray(body.blocks)
+  ) {
+    throw new ChatRouterError(
+      'Unexpected response from the AI backend. It may be running an ' +
+        'incompatible version of the chat API.'
+    );
+  }
+  return { message: body.message, blocks: body.blocks };
+}
+
+export class ChatRouter {
+  /**
+   * @param _notebook What the conversation's notebook holds -- the one its
+   *   answers are placed in -- or null if there is nothing to send. Asked on
+   *   every request, so it follows the conversation rather than whichever tab
+   *   happens to be active.
+   */
+  constructor(
+    private _settings: ISettingRegistry.ISettings,
+    private _notebook: () => Promise<INotebookSnapshot | null>
+  ) {}
+
+  async route(
+    prompt: string,
+    chatHistory: ChatMessage[] = [],
+    signal?: AbortSignal,
+    onProgress?: (progress: Progress) => void
+  ): Promise<RouteResult> {
+    const { payload, isCodeCell, context } = await this._gather(
+      prompt,
+      chatHistory
+    );
+    const data = await this._send('/api/chat', payload, signal, onProgress);
+    return {
+      response: asOceanumResponse(data),
+      hasCodeCellSelected: isCodeCell && context.trim().length > 0
+    };
+  }
+
+  /**
+   * The notebook half of the execute loop: the code ran in the user's own
+   * kernel, here is what happened, what next? Same context as `route`, plus
+   * every run so far, so the agent sees the whole chain it is continuing.
+   */
+  async observe(
+    prompt: string,
+    chatHistory: ChatMessage[],
+    runs: ObservedRun[],
+    signal?: AbortSignal,
+    onProgress?: (progress: Progress) => void
+  ): Promise<OceanumResponse> {
+    const { payload } = await this._gather(prompt, chatHistory);
+    const data = await this._send(
+      '/api/chat/observe',
+      { ...payload, runs },
+      signal,
+      onProgress
+    );
+    return asOceanumResponse(data);
+  }
+
+  private async _gather(
+    prompt: string,
+    chatHistory: ChatMessage[]
+  ): Promise<{ payload: ChatPayload; isCodeCell: boolean; context: string }> {
+    let context = '';
+    let isCodeCell = false;
+    let notebookCells: string[] = [];
+
+    try {
+      const snapshot = await this._notebook();
+      if (snapshot) {
+        notebookCells = formatNotebookCells(snapshot.cells);
+        // Answers are placed in this same notebook, so its selected cell is
+        // the one a code answer may replace.
+        if (snapshot.selected) {
+          context = snapshot.selected.source;
+          isCodeCell = snapshot.selected.isCode;
+        }
+      }
+    } catch {
+      // context is optional — never throw
+    }
+
+    // Build payload with all context
+    const payload: ChatPayload = { prompt };
+
+    if (context) {
+      if (isCodeCell) {
+        payload.codeContext = context;
+      } else {
+        payload.context = context;
+      }
+    }
+
+    // Include chat history (excluding the current prompt which is already in 'prompt')
+    if (chatHistory.length > 0) {
+      payload.chatHistory = chatHistory;
+    }
+
+    // Include the conversation's notebook cells
+    if (notebookCells.length > 0) {
+      payload.notebookCells = notebookCells;
+    }
+
+    return { payload, isCodeCell, context };
+  }
+
+  private async _send(
+    path: string,
+    payload: unknown,
+    signal?: AbortSignal,
+    onProgress?: (progress: Progress) => void
+  ): Promise<unknown> {
+    const token = this._settings.get('datameshToken').composite as string;
+    if (!token) {
+      throw new ChatRouterError(
+        'Datamesh token not configured. Set your token in Settings → Oceanum.io.'
+      );
+    }
+
+    let response: Response;
+    try {
+      response = await fetch(`${OCEANUM_AI_BACKEND_URL}${path}`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Datamesh-Token': token,
+          // Ask for the streamed form only when someone is listening. The
+          // server requires the media type to be NAMED -- a wildcard never
+          // selects it -- so omitting this is what keeps the plain JSON path
+          // byte-identical to what it always was.
+          ...(onProgress ? { Accept: 'text/event-stream' } : {})
+        },
+        body: JSON.stringify(payload),
+        signal
+      });
+    } catch (err) {
+      // The user pressed Stop. Not a failure, and not "could not reach"; the
+      // caller checks `signal.aborted` and stays quiet.
+      if (signal?.aborted) {
+        throw err;
+      }
+      throw new ChatRouterError(
+        `Could not reach Oceanum AI backend at ${OCEANUM_AI_BACKEND_URL}. Is it running?`
+      );
+    }
+
+    if (response.status === 401) {
+      throw new ChatRouterError('Invalid or expired Datamesh token.', 401);
+    }
+
+    if (!response.ok) {
+      let detail = '';
+      try {
+        const body = await response.json();
+        detail = body.detail ?? JSON.stringify(body);
+      } catch {
+        detail = response.statusText;
+      }
+      throw new ChatRouterError(`Backend error: ${detail}`, response.status);
+    }
+
+    // Stop can also land while the body is still being read; that rejects
+    // here, not in the fetch above, and the caller treats it the same way.
+    if (onProgress && isEventStream(response)) {
+      return this._drain(response, onProgress, signal);
+    }
+    return response.json();
+  }
+
+  /**
+   * Read the streamed form, reporting progress, and return the final answer.
+   *
+   * The `done` event is authoritative: the events before it are for the user
+   * to look at, not for the client to reassemble. Anything else and a client
+   * that missed a frame would silently answer with less than the agent said.
+   */
+  private async _drain(
+    response: Response,
+    onProgress: (progress: Progress) => void,
+    signal?: AbortSignal
+  ): Promise<unknown> {
+    if (!response.body) {
+      // A proxy buffered the whole response, or this runtime has no
+      // ReadableStream. Either way there is nothing to stream; the body is
+      // still the answer, so fall back rather than fail.
+      return response.json();
+    }
+
+    let answer: unknown;
+    try {
+      for await (const event of readSse(response.body, signal)) {
+        if (event.event === 'status') {
+          const data = parseJson<Progress>(event.data);
+          if (data?.phase) {
+            onProgress(data);
+          }
+        } else if (event.event === 'done') {
+          answer = parseJson<unknown>(event.data);
+        } else if (event.event === 'error') {
+          const data = parseJson<{ detail?: string; status_code?: number }>(
+            event.data
+          );
+          // The status was 200 before this could happen, so the failure travels
+          // in the frame and there was nothing for the check above to throw on.
+          throw new ChatRouterError(
+            `Backend error: ${data?.detail ?? 'the request failed'}`,
+            data?.status_code
+          );
+        }
+      }
+    } catch (err) {
+      // Stop fails the read with an AbortError, which the caller reports as
+      // Stop, and an `error` event is already the chat's error. Anything else
+      // is the connection going away mid-answer -- a redeploy, the network --
+      // which fetch reports as a bare TypeError ("terminated"). Left as it
+      // was, it reached the command as unexpected and the chat showed nothing.
+      if (signal?.aborted || err instanceof ChatRouterError) {
+        throw err;
+      }
+      throw new ChatRouterError(
+        'The connection to Oceanum AI was lost before the response was complete.'
+      );
+    }
+
+    if (answer === undefined) {
+      // The stream ended without its terminal event -- a dropped connection,
+      // or a proxy closing a response that looked idle. Treated as a failure
+      // rather than a partial answer, which is indistinguishable from a
+      // complete one once it reaches the chat.
+      if (signal?.aborted) {
+        throw new DOMException('Aborted', 'AbortError');
+      }
+      throw new ChatRouterError('The response ended before it was complete.');
+    }
+    return answer;
+  }
+}
+
+function isEventStream(response: Response): boolean {
+  return (
+    response.headers.get('content-type')?.includes('text/event-stream') ?? false
+  );
+}
+
+/** Parse one event's data, returning null rather than throwing: a malformed
+ * frame should cost a progress update, not the answer. */
+function parseJson<T>(data: string): T | null {
+  try {
+    return JSON.parse(data) as T;
+  } catch {
+    return null;
+  }
+}
+
+interface ChatPayload {
+  prompt: string;
+  context?: string;
+  codeContext?: string;
+  chatHistory?: ChatMessage[];
+  notebookCells?: string[];
+}

package/src/constants.ts

@@ -0,0 +1,16 @@
+/**
+ * Build-time constants for Oceanum AI integration.
+ * These values are compiled into the extension.
+ */
+
+/** URL of the Oceanum AI backend service */
+export const OCEANUM_AI_BACKEND_URL = 'https://ai.oceanum.io';
+
+/**
+ * Safety net on observe requests per prompt. The server's EXECUTE_MAX_ROUNDS
+ * is what actually caps the chain (at its cap it answers without code, which
+ * ends the loop); this only stops a client talking to a server that keeps
+ * sending code, and is checked after each observe so the server's explanation
+ * turn is always requested.
+ */
+export const MAX_OBSERVE_ROUNDS = 8;

package/src/conversationPin.ts

@@ -0,0 +1,148 @@
+import type { NotebookPanel } from '@jupyterlab/notebook';
+
+/**
+ * What ConversationPin needs from JupyterLab -- passed in, so the pin can be
+ * tested without it. Both `create` and `reopen` must resolve only once the
+ * notebook's contents have loaded: loading replaces every cell, so anything
+ * placed before then is wiped.
+ */
+export interface INotebookHost {
+  /** The notebook in the active main-area tab, or null if that is not one. */
+  activeTab(): NotebookPanel | null;
+  /** A new notebook, made the active tab. Null if none can be created. */
+  create(): Promise<NotebookPanel | null>;
+  /** The notebook at `path`, opened again as a tab. Null if it cannot be. */
+  reopen(path: string): Promise<NotebookPanel | null>;
+  /** Bring `panel`'s tab to the front. */
+  activate(panel: NotebookPanel): void;
+}
+
+/**
+ * The notebook the current conversation lives in: what the agent is shown,
+ * and where its answers go.
+ *
+ * Pinned when the conversation starts -- New chat, or the first message after
+ * the panel opens -- to the notebook in the ACTIVE TAB or, when that tab is
+ * not a notebook, to a new notebook made the active tab. Kept for the whole
+ * conversation: switching tabs does not move it, a rename is followed, and a
+ * pinned notebook that has been closed is opened again when an answer has
+ * cells to place in it. The active tab rather than the tracker's current
+ * notebook, which is the LAST-FOCUSED notebook even with a terminal or a text
+ * file in front.
+ */
+export class ConversationPin {
+  private _panel: NotebookPanel | null = null;
+  // Kept separately so a closed notebook can be found again.
+  private _path: string | null = null;
+  private _started = false;
+  // Starting, re-opening and creating happen one at a time: a second New chat
+  // must find the notebook the first one created as the active tab rather
+  // than create another.
+  private _queue: Promise<unknown> = Promise.resolve();
+
+  constructor(private readonly _host: INotebookHost) {}
+
+  /** Start a new conversation. Resolves to its notebook's name. */
+  start(): Promise<string | null> {
+    return this._serial(() => this._startNow());
+  }
+
+  /**
+   * Start the conversation if nothing has, and report its notebook's name
+   * either way.
+   */
+  ensure(): Promise<string | null> {
+    return this._serial(async () =>
+      this._started ? this.name() : this._startNow()
+    );
+  }
+
+  /**
+   * The conversation's notebook if it is open, starting the conversation if
+   * nothing has -- but NOT opening a closed one again: that is for placing an
+   * answer, not for asking a question. See path() for reading a closed one.
+   */
+  current(): Promise<NotebookPanel | null> {
+    return this._serial(async () => {
+      if (!this._started) {
+        await this._startNow();
+      }
+      return this._live();
+    });
+  }
+
+  /**
+   * The conversation's notebook, opened again if it has been closed. When it
+   * cannot be -- deleted, or gone some other way -- a new notebook takes its
+   * place, so the conversation always has one. Null only if none can be made.
+   */
+  notebook(): Promise<NotebookPanel | null> {
+    return this._serial(async () => {
+      if (!this._started) {
+        await this._startNow();
+      }
+      const live = this._live();
+      if (live) {
+        return live;
+      }
+      const reopened = this._path ? await this._host.reopen(this._path) : null;
+      this._pin(reopened ?? (await this._host.create()));
+      return this._panel;
+    });
+  }
+
+  /** The conversation's notebook, brought to the front: see notebook(). */
+  async show(): Promise<NotebookPanel | null> {
+    const panel = await this.notebook();
+    if (panel) {
+      this._host.activate(panel);
+    }
+    return panel;
+  }
+
+  /** Where the notebook's file is -- its last known place while it is closed. */
+  path(): string | null {
+    return this._path;
+  }
+
+  /** The notebook's name -- its last known one while it is closed. */
+  name(): string | null {
+    const live = this._live();
+    if (live) {
+      return live.title.label;
+    }
+    return this._path ? (this._path.split('/').pop() ?? this._path) : null;
+  }
+
+  private _live(): NotebookPanel | null {
+    return this._panel && !this._panel.isDisposed ? this._panel : null;
+  }
+
+  private async _startNow(): Promise<string | null> {
+    this._pin(this._host.activeTab() ?? (await this._host.create()));
+    this._started = true;
+    return this.name();
+  }
+
+  private _pin(panel: NotebookPanel | null): void {
+    this._panel?.context.pathChanged.disconnect(this._onPathChanged, this);
+    this._panel = panel;
+    this._path = panel?.context.path ?? null;
+    // Follows a rename or move made while it is open, so that a notebook
+    // renamed and then closed is found again under its new name.
+    panel?.context.pathChanged.connect(this._onPathChanged, this);
+  }
+
+  private _onPathChanged(_: unknown, path: string): void {
+    this._path = path;
+  }
+
+  private _serial<T>(task: () => Promise<T>): Promise<T> {
+    const run = this._queue.then(task);
+    // A failed step is reported to its caller; it must not block the next.
+    this._queue = run.catch(() => {
+      /* swallowed here only */
+    });
+    return run;
+  }
+}

package/src/global.d.ts

@@ -0,0 +1,5 @@
+declare global {
+  var datameshToken: string;
+  var injectToken: boolean;
+}
+export {};

package/src/handler.ts

@@ -0,0 +1,46 @@
+import { URLExt } from '@jupyterlab/coreutils';
+
+import { ServerConnection } from '@jupyterlab/services';
+
+/**
+ * Call the API extension
+ *
+ * @param endPoint API REST end point for the extension
+ * @param init Initial values for the request
+ * @returns The response body interpreted as JSON
+ */
+export async function requestAPI<T>(
+  endPoint = '',
+  init: RequestInit = {}
+): Promise<T> {
+  // Make request to Jupyter API
+  const settings = ServerConnection.makeSettings();
+  const requestUrl = URLExt.join(
+    settings.baseUrl,
+    'oceanum', // API Namespace
+    endPoint
+  );
+
+  let response: Response;
+  try {
+    response = await ServerConnection.makeRequest(requestUrl, init, settings);
+  } catch (error) {
+    throw new ServerConnection.NetworkError(error as any);
+  }
+
+  let data: any = await response.text();
+
+  if (data.length > 0) {
+    try {
+      data = JSON.parse(data);
+    } catch (error) {
+      console.log('Not a JSON response body.', response);
+    }
+  }
+
+  if (!response.ok) {
+    throw new ServerConnection.ResponseError(response, data.message || data);
+  }
+
+  return data;
+}