@oceanum/oceanumlab 4.6.0

package/src/__tests__/sse.spec.ts

@@ -0,0 +1,304 @@
+import { readSse } from '../sse';
+import {
+  describeProgress,
+  onProgress,
+  reporterFor,
+  type Progress
+} from '../progress';
+
+/**
+ * A stand-in for the browser's ReadableStream, because jsdom has none.
+ *
+ * `readSse` uses exactly three things from a body -- `getReader()`, then
+ * `read()` and `releaseLock()` on the reader -- so this supplies those and
+ * nothing else. Building it here rather than reaching for a polyfill also
+ * gives the tests what they actually need: control of where one chunk ends and
+ * the next begins, which is the thing the network decides and the parser has
+ * to survive.
+ */
+function chunkedStream(chunks: Uint8Array[]): ReadableStream<Uint8Array> {
+  let index = 0;
+  return {
+    getReader: () => ({
+      read: async (): Promise<{ done: boolean; value?: Uint8Array }> =>
+        index < chunks.length
+          ? { done: false, value: chunks[index++] }
+          : { done: true, value: undefined },
+      releaseLock: (): void => undefined
+    })
+  } as unknown as ReadableStream<Uint8Array>;
+}
+
+function streamOf(...chunks: string[]): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  return chunkedStream(chunks.map(chunk => encoder.encode(chunk)));
+}
+
+async function collect(
+  stream: ReadableStream<Uint8Array>,
+  signal?: AbortSignal
+): Promise<Array<{ event: string; data: string }>> {
+  const out: Array<{ event: string; data: string }> = [];
+  for await (const event of readSse(stream, signal)) {
+    out.push({ event: event.event, data: event.data });
+  }
+  return out;
+}
+
+describe('readSse', () => {
+  it('reads one event per frame', async () => {
+    const events = await collect(
+      streamOf(
+        'event: status\ndata: {"phase":"generating"}\n\n',
+        'event: done\ndata: {"message":"hi"}\n\n'
+      )
+    );
+
+    expect(events).toEqual([
+      { event: 'status', data: '{"phase":"generating"}' },
+      { event: 'done', data: '{"message":"hi"}' }
+    ]);
+  });
+
+  it('reassembles a frame split across chunks', async () => {
+    // The network splits wherever it likes; a frame is not a packet.
+    const events = await collect(
+      streamOf('event: sta', 'tus\ndata: {"pha', 'se":"generating"}\n\n')
+    );
+
+    expect(events).toEqual([
+      { event: 'status', data: '{"phase":"generating"}' }
+    ]);
+  });
+
+  it('reassembles a multi-byte character split across chunks', async () => {
+    // A UTF-8 sequence has no obligation to arrive whole. Decoding each chunk
+    // independently mangles it, and a dataset name with an accent is what
+    // finds that in production rather than in a test.
+    const payload = '{"tool":"café"}';
+    const bytes = new TextEncoder().encode(
+      `event: status\ndata: ${payload}\n\n`
+    );
+    const split = bytes.indexOf(0xc3); // the first byte of "é"
+
+    const events = await collect(
+      chunkedStream([bytes.slice(0, split + 1), bytes.slice(split + 1)])
+    );
+
+    expect(events).toEqual([{ event: 'status', data: payload }]);
+  });
+
+  it('ignores keepalive comments', async () => {
+    // The backend sends these during a long wait. They carry nothing, and a
+    // client that treated one as an event would show a blank status.
+    const events = await collect(
+      streamOf(': keepalive\n\n', 'event: done\ndata: {"message":"hi"}\n\n')
+    );
+
+    expect(events).toEqual([{ event: 'done', data: '{"message":"hi"}' }]);
+  });
+
+  it('drops a frame with no data rather than yielding an empty one', async () => {
+    const events = await collect(
+      streamOf('event: status\n\n', 'event: done\ndata: {}\n\n')
+    );
+
+    expect(events).toEqual([{ event: 'done', data: '{}' }]);
+  });
+
+  it('stops when the signal is aborted', async () => {
+    // Stop must end the read, not merely stop the caller looking at it.
+    const controller = new AbortController();
+    controller.abort();
+
+    const events = await collect(
+      streamOf('event: done\ndata: {"message":"hi"}\n\n'),
+      controller.signal
+    );
+
+    expect(events).toEqual([]);
+  });
+});
+
+describe('describeProgress', () => {
+  it('names the lookup the agent stopped to do', () => {
+    expect(describeProgress({ phase: 'tool', tool: 'search_catalog' })).toBe(
+      'Searching the catalogue…'
+    );
+  });
+
+  it('falls back to Thinking when there is no progress yet', () => {
+    // A backend that does not stream, or a proxy that buffered the stream
+    // away, degrades to exactly what this said before.
+    expect(describeProgress(null)).toBe('Thinking…');
+  });
+
+  it('does not leak the internal name of a tool it has not been taught', () => {
+    expect(
+      describeProgress({ phase: 'tool', tool: 'some_new_internal_tool' })
+    ).toBe('Looking something up…');
+  });
+
+  it('reads a new phase as progress rather than as a blank', () => {
+    expect(describeProgress({ phase: 'something_new' })).toBe('Working…');
+  });
+
+  it('gives a name that is also a built-in property the generic label', () => {
+    // Names come off the stream. `__proto__` must not come back as
+    // Object.prototype -- React cannot render an object -- nor `toString` as a
+    // function.
+    for (const name of [
+      '__proto__',
+      'toString',
+      'constructor',
+      'hasOwnProperty'
+    ]) {
+      expect(describeProgress({ phase: 'tool', tool: name })).toBe(
+        'Looking something up…'
+      );
+      expect(describeProgress({ phase: name })).toBe('Working…');
+    }
+  });
+});
+
+describe('phases the client reports about itself', () => {
+  // Everything else names something the AGENT is doing. These two are the
+  // notebook's turn, and they exist because the last agent phase used to stay
+  // on screen while a cell ran -- telling the user the agent was reading
+  // dataset details when their own code was executing. That is a worse claim
+  // than the vague "Thinking…" it replaced.
+
+  it('says the code is running', () => {
+    expect(describeProgress({ phase: 'running' })).toBe('Running the code…');
+  });
+
+  it('says the code is being placed when auto-run is off', () => {
+    expect(describeProgress({ phase: 'placing' })).toBe(
+      'Adding the code to the notebook…'
+    );
+  });
+
+  it('never claims the agent is working while the notebook is', () => {
+    // The specific regression: a phase the client reports must not fall
+    // through to wording about the agent.
+    for (const phase of ['running', 'placing']) {
+      expect(describeProgress({ phase })).not.toBe('Thinking…');
+      expect(describeProgress({ phase })).not.toBe('Working…');
+    }
+  });
+});
+
+describe('line endings other than LF', () => {
+  // The spec allows CRLF, bare CR and LF. Our backend sends LF, but that is a
+  // statement about one hop -- anything between it and the browser may rewrite
+  // them, and the failure if it does is TOTAL rather than partial: the frame
+  // separator never matches, zero events parse, and the caller reports the
+  // response as incomplete. Measured before this was handled: 0 events from a
+  // well-formed CRLF stream.
+
+  it('reads a CRLF stream', () => {
+    return expect(
+      collect(
+        streamOf(
+          'event: status\r\ndata: {"phase":"generating"}\r\n\r\n',
+          'event: done\r\ndata: {"message":"hi"}\r\n\r\n'
+        )
+      )
+    ).resolves.toEqual([
+      { event: 'status', data: '{"phase":"generating"}' },
+      { event: 'done', data: '{"message":"hi"}' }
+    ]);
+  });
+
+  it('reads a bare-CR stream', async () => {
+    const events = await collect(
+      streamOf('event: done\rdata: {"message":"hi"}\r\r')
+    );
+
+    expect(events).toEqual([{ event: 'done', data: '{"message":"hi"}' }]);
+  });
+
+  it('does not invent a frame when a CRLF is split across chunks', async () => {
+    // The subtlety the fix exists for. A chunk ending in `\r` whose `\n`
+    // arrives next must not be converted early: doing so manufactures a blank
+    // line, and a blank line is a frame boundary, so one event becomes two
+    // malformed ones.
+    const events = await collect(
+      streamOf('event: done\r\ndata: {"message":"hi"}\r', '\n\r\n')
+    );
+
+    expect(events).toEqual([{ event: 'done', data: '{"message":"hi"}' }]);
+  });
+
+  it('leaves no carriage return in the payload', async () => {
+    // A stray `\r` on the end of the data would break JSON.parse for the
+    // caller, which is the same silent failure one layer along.
+    const events = await collect(
+      streamOf('event: done\r\ndata: {"message":"hi"}\r\n\r\n')
+    );
+
+    expect(events[0].data).not.toContain('\r');
+    expect(() => JSON.parse(events[0].data)).not.toThrow();
+  });
+});
+
+describe('Stop while a read is in flight', () => {
+  it('ends the read with the abort, having yielded what arrived first', async () => {
+    // The already-aborted case above is the easy one. The real Stop lands while
+    // a read is pending, and fetch fails that read.
+    const controller = new AbortController();
+    let reads = 0;
+    const body = {
+      getReader: () => ({
+        read: (): Promise<{ done: boolean; value?: Uint8Array }> => {
+          reads += 1;
+          if (reads === 1) {
+            return Promise.resolve({
+              done: false,
+              value: new TextEncoder().encode(
+                'event: status\ndata: {"phase":"generating"}\n\n'
+              )
+            });
+          }
+          return new Promise((_ok, fail) => {
+            controller.signal.addEventListener('abort', () =>
+              fail(new DOMException('Aborted', 'AbortError'))
+            );
+          });
+        },
+        releaseLock: (): void => undefined
+      })
+    } as unknown as ReadableStream<Uint8Array>;
+
+    const seen: string[] = [];
+    const reading = (async () => {
+      for await (const event of readSse(body, controller.signal)) {
+        seen.push(event.event);
+      }
+    })();
+    await new Promise(resolve => setTimeout(resolve, 0));
+    controller.abort();
+
+    await expect(reading).rejects.toMatchObject({ name: 'AbortError' });
+    expect(seen).toEqual(['status']);
+  });
+});
+
+describe('reporterFor', () => {
+  it('speaks only while its run is the current one', () => {
+    // A replaced run can take a while to unwind; nothing it reports on the way
+    // out may land on the new run's progress line -- not even its "done".
+    let current = true;
+    const heard: Array<Progress | null> = [];
+    const unsubscribe = onProgress(progress => heard.push(progress));
+    const report = reporterFor(() => current);
+
+    report({ phase: 'generating' });
+    current = false;
+    report({ phase: 'running' });
+    report(null);
+    unsubscribe();
+
+    expect(heard).toEqual([{ phase: 'generating' }]);
+  });
+});

package/src/aiLoop.ts

@@ -0,0 +1,140 @@
+import type { ChatMessage, OceanumResponse } from './chatRouter';
+import type { ObservedRun } from './notebookRun';
+
+/** What `inject` reports back: the chat text, and what ran if anything did. */
+export interface PlacedResponse {
+  message: string;
+  runs: ObservedRun[];
+  /**
+   * A code cell could not be executed at all (no kernel, pending input, the
+   * notebook closed, Stop). Its run says so; observing it would only bring
+   * back more code that cannot run either.
+   */
+  halted?: boolean;
+}
+
+/** The pieces the loop needs, injected so it can be tested without a notebook. */
+export interface LoopDeps {
+  route(
+    prompt: string,
+    history: ChatMessage[],
+    signal: AbortSignal
+  ): Promise<{
+    response: OceanumResponse;
+    hasCodeCellSelected: boolean;
+  }>;
+  observe(
+    prompt: string,
+    history: ChatMessage[],
+    runs: ObservedRun[],
+    signal: AbortSignal
+  ): Promise<OceanumResponse>;
+  place(
+    response: OceanumResponse,
+    options: { replaceCodeCell: boolean; autoRun: boolean; signal: AbortSignal }
+  ): Promise<PlacedResponse>;
+}
+
+export interface LoopOptions {
+  /** Run code cells as they are placed. Workflow 1; required for 2. */
+  autoRunCode: boolean;
+  /** Send each run's output back and place what comes next. Workflow 2. */
+  iterate: boolean;
+  /** Safety net on observe requests; see `runChatLoop`. */
+  maxRounds: number;
+  signal: AbortSignal;
+}
+
+export const STOPPED = 'Stopped.';
+
+/**
+ * One prompt, start to finish, under the two switches.
+ *
+ * The loop lives here rather than on the server because the CLIENT owns the
+ * kernel: only it can run a cell and read what came back. The server sees one
+ * turn at a time through `/api/chat/observe`.
+ *
+ *   autoRunCode off              -> place blocks, stop.           (workflow 3)
+ *   autoRunCode on, iterate off  -> place, run, stop.             (workflow 1)
+ *   autoRunCode on, iterate on   -> place, run, observe, repeat.  (workflow 2)
+ *
+ * `iterate` without `autoRunCode` is inert: nothing ran, so there is nothing
+ * to observe. That falls out of the data (no runs) rather than a guard.
+ *
+ * Rounds end when nothing ran (the agent answered without code, so it is
+ * done), or on Stop. The server enforces its own EXECUTE_MAX_ROUNDS: at the
+ * cap it still answers, explaining the last run with any code stripped, and
+ * that code-free answer ends the loop here. `maxRounds` is therefore only a
+ * safety net against a server that keeps sending code, checked AFTER the
+ * observe so the server's explanation turn is always requested. Every round's
+ * message is kept: a chain that took three steps should read as three steps,
+ * not as the last one.
+ */
+export async function runChatLoop(
+  prompt: string,
+  history: ChatMessage[],
+  deps: LoopDeps,
+  options: LoopOptions
+): Promise<string> {
+  const { signal } = options;
+  const messages: string[] = [];
+  const runs: ObservedRun[] = [];
+
+  let response: OceanumResponse;
+  let replaceCodeCell: boolean;
+  try {
+    const first = await deps.route(prompt, history, signal);
+    response = first.response;
+    replaceCodeCell = first.hasCodeCellSelected;
+  } catch (err) {
+    if (signal.aborted) {
+      return STOPPED;
+    }
+    throw err;
+  }
+  if (signal.aborted) {
+    return STOPPED;
+  }
+
+  for (let round = 1; ; round++) {
+    const placed = await deps.place(response, {
+      replaceCodeCell,
+      autoRun: options.autoRunCode,
+      signal
+    });
+    messages.push(placed.message);
+    runs.push(...placed.runs);
+    replaceCodeCell = false;
+
+    if (signal.aborted) {
+      messages.push(STOPPED);
+      break;
+    }
+    if (!options.iterate || placed.runs.length === 0 || placed.halted) {
+      // Nothing ran this round, or nothing could, so there is nothing to
+      // observe.
+      break;
+    }
+    if (round > options.maxRounds) {
+      break;
+    }
+
+    try {
+      response = await deps.observe(prompt, history, runs, signal);
+    } catch (err) {
+      // Stop pressed while the request was in flight. What was already placed
+      // and explained stays in the chat; only the next step is dropped.
+      if (signal.aborted) {
+        messages.push(STOPPED);
+        break;
+      }
+      throw err;
+    }
+    if (signal.aborted) {
+      messages.push(STOPPED);
+      break;
+    }
+  }
+
+  return messages.filter(m => m.trim().length > 0).join('\n\n');
+}