@neutrome/lilsdk 0.6.3 → 0.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neutrome/lilsdk",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

package/src/managed/collapsed-reasoner.ts

@@ -7,6 +7,7 @@ import {
   findThinkingBlocks,
   Opcode,
   prependSystemPrompt,
+  ProgramView,
   removeInstructions,
   type Program,
 } from "@neutrome/lil-engine";
@@ -19,9 +20,13 @@ const DEFAULT_PROMPT =
   "Summarize the reasoning below as a concise user-facing progress update. Return an empty response when there is no useful update.";
 const DEFAULT_FORCED_PROMPT =
   "Give a concise user-facing progress update based only on the reasoning below. Return an empty response when no update is useful.";
+const INITIAL_PROMPT =
+  "Based only on the user's request below, give one concise user-facing update about what you are starting. Do not claim progress or results.";
 
 /** Options accepted by {@link createCollapsedReasoner}. */
 export type CollapsedReasonerOptions = {
+  /** Prompt used to initialize the reasoner's state. */
+  initialPrompt?: string;
   /** Prompt used for periodic progress updates. */
   prompt?: string;
   /** Prompt used when an update must be attempted. */
@@ -52,21 +57,30 @@ export function createCollapsedReasoner(
       const response = await ctx.invoke(reasoner, request);
       const reasoning = extractThinkingText(response);
       const concealed = withoutThinking(response);
-      if (!reasoning) return concealed;
+      if (!reasoning || extractContentText(concealed)) return concealed;
 
-      const summary = await summarize(ctx, summarizer, settings.forcedPrompt, reasoning);
+      const summary = await summarize(
+        ctx,
+        summarizer,
+        settings.forcedPrompt,
+        reasoning,
+      );
       return summary ? appendAssistantThinking(concealed, summary) : concealed;
     },
 
     async *stream(request, ctx) {
-      const source = ctx.invokeStream(reasoner, request)[Symbol.asyncIterator]();
+      const source = ctx
+        .invokeStream(reasoner, request)
+        [Symbol.asyncIterator]();
       let raw = "";
       let startedAt: number | undefined;
       let normalAt = 0;
       let forcedAt = 0;
       let summaries: Promise<void> = Promise.resolve();
       const ready: string[] = [];
-      let summaryError: unknown;
+      let phase = 0;
+      let acceptsSummaries = true;
+      let summaryError: { phase: number; error: unknown } | undefined;
       let wake: (() => void) | undefined;
       let wakePromise = nextWake();
       const terminal: Program[] = [];
@@ -75,16 +89,30 @@ export function createCollapsedReasoner(
         wake?.();
         wakePromise = nextWake();
       };
+      const initial = summarizeInitial(ctx, summarizer, request, settings.initialPrompt).then(
+        (summary) => {
+          if (summary && acceptsSummaries && phase === 0) ready.push(summary);
+          notify();
+        },
+        (error: unknown) => {
+          if (acceptsSummaries && phase === 0)
+            summaryError = { phase: 0, error };
+          notify();
+        },
+      );
       const enqueue = (prompt: string, force: boolean) => {
-        if (!raw) return;
+        if (!acceptsSummaries || !raw) return;
         const interval = raw;
+        const summaryPhase = phase;
         raw = "";
         summaries = summaries.then(async () => {
           const summary = await summarize(ctx, summarizer, prompt, interval);
-          if (summary) ready.push(summary);
+          if (summary && acceptsSummaries && phase === summaryPhase)
+            ready.push(summary);
         });
         void summaries.then(notify, (error: unknown) => {
-          summaryError = error;
+          if (acceptsSummaries && phase === summaryPhase)
+            summaryError = { phase: summaryPhase, error };
           notify();
         });
         if (force) normalAt = Date.now();
@@ -93,11 +121,12 @@ export function createCollapsedReasoner(
       let next = source.next();
       try {
         for (;;) {
-          if (summaryError) throw summaryError;
-          while (ready.length > 0) yield thinkingChunk(ready.shift()!);
+          if (summaryError?.phase === phase) throw summaryError.error;
+          while (acceptsSummaries && ready.length > 0)
+            yield thinkingChunk(ready.shift()!);
 
           const now = Date.now();
-          if (startedAt !== undefined) {
+          if (acceptsSummaries && startedAt !== undefined) {
             if (now >= forcedAt) {
               enqueue(settings.forcedPrompt, true);
               forcedAt = now + settings.forcedInterval;
@@ -111,34 +140,55 @@ export function createCollapsedReasoner(
             }
           }
 
-          const due = startedAt === undefined
-            ? undefined
-            : Math.max(0, Math.min(normalAt, forcedAt) - Date.now());
+          const due =
+            !acceptsSummaries || startedAt === undefined
+              ? undefined
+              : Math.max(0, Math.min(normalAt, forcedAt) - Date.now());
           const event = await Promise.race([
             next.then((result) => ({ type: "source" as const, result })),
             wakePromise.then(() => ({ type: "summary" as const })),
-            ...(due === undefined ? [] : [delay(due).then(() => ({ type: "timer" as const }))]),
+            ...(due === undefined
+              ? []
+              : [delay(due).then(() => ({ type: "timer" as const }))]),
           ]);
           if (event.type !== "source") continue;
           next = source.next();
           if (event.result.done) break;
 
-          const visible = splitStreamChunk(event.result.value, terminal, (text) => {
-            raw += text;
-            if (startedAt === undefined) {
-              const timestamp = Date.now();
-              startedAt = timestamp;
-              normalAt = timestamp + settings.interval;
-              forcedAt = timestamp + settings.forcedInterval;
-            }
-          });
+          const visible = splitStreamChunk(
+            event.result.value,
+            terminal,
+            (text) => {
+              if (!text) return;
+              if (!acceptsSummaries) acceptsSummaries = true;
+              raw += text;
+              if (startedAt === undefined) {
+                const timestamp = Date.now();
+                startedAt = timestamp;
+                normalAt = timestamp + settings.interval;
+                forcedAt = timestamp + settings.forcedInterval;
+              }
+            },
+            (text) => {
+              if (!text || !acceptsSummaries) return;
+              acceptsSummaries = false;
+              phase += 1;
+              raw = "";
+              startedAt = undefined;
+              ready.length = 0;
+              summaries = Promise.resolve();
+            },
+          );
           if (visible.code.length > 0) yield visible;
         }
 
-        enqueue(settings.forcedPrompt, true);
-        await summaries;
-        if (summaryError) throw summaryError;
-        while (ready.length > 0) yield thinkingChunk(ready.shift()!);
+        if (acceptsSummaries) {
+          enqueue(settings.forcedPrompt, true);
+          await Promise.all([summaries, ...(phase === 0 ? [initial] : [])]);
+        }
+        if (summaryError?.phase === phase) throw summaryError.error;
+        if (acceptsSummaries)
+          while (ready.length > 0) yield thinkingChunk(ready.shift()!);
         yield* terminal;
       } finally {
         await source.return?.();
@@ -154,17 +204,23 @@ export function createCollapsedReasoner(
 }
 
 function parseOptions(options: CollapsedReasonerOptions) {
-  const interval = positiveDuration(options.interval ?? DEFAULT_INTERVAL, "interval");
+  const interval = positiveDuration(
+    options.interval ?? DEFAULT_INTERVAL,
+    "interval",
+  );
   const forcedInterval = positiveDuration(
     options.forcedInterval ?? DEFAULT_FORCED_INTERVAL,
     "forcedInterval",
   );
   if (forcedInterval < interval) {
-    throw new RangeError("forcedInterval must be greater than or equal to interval");
+    throw new RangeError(
+      "forcedInterval must be greater than or equal to interval",
+    );
   }
   return {
     interval,
     forcedInterval,
+    initialPrompt: options.initialPrompt ?? INITIAL_PROMPT,
     prompt: options.prompt ?? DEFAULT_PROMPT,
     forcedPrompt: options.forcedPrompt ?? DEFAULT_FORCED_PROMPT,
   };
@@ -183,13 +239,32 @@ async function summarize(
   prompt: string,
   reasoning: string,
 ): Promise<string> {
-  const request = prependSystemPrompt(appendUserMessage(createProgram(), reasoning), prompt);
+  const request = prependSystemPrompt(
+    appendUserMessage(createProgram(), reasoning),
+    prompt,
+  );
   return extractContentText(await ctx.invoke(summarizer, request)).trim();
 }
 
+async function summarizeInitial(
+  ctx: ExecutorContext,
+  summarizer: ExecutorInput,
+  request: Program,
+  prompt: string,
+): Promise<string> {
+  const content = new ProgramView(request).messages
+    .filter((message) => message.role === "user")
+    .at(-1)?.text.trim();
+  if (!content) return "";
+  return summarize(ctx, summarizer, prompt, content);
+}
+
 function withoutThinking(program: Program): Program {
   const indices = findThinkingBlocks(program).flatMap((block) =>
-    Array.from({ length: block.end - block.start + 1 }, (_, offset) => block.start + offset),
+    Array.from(
+      { length: block.end - block.start + 1 },
+      (_, offset) => block.start + offset,
+    ),
   );
   return removeInstructions(program, indices);
 }
@@ -209,25 +284,41 @@ function splitStreamChunk(
   chunk: Program,
   terminal: Program[],
   onThinking: (text: string) => void,
+  onBody: (text: string) => void,
 ): Program {
   const visible = [] as Program["code"];
   const ending = [] as Program["code"];
   for (const instruction of chunk.code) {
-    if (instruction.opcode === Opcode.STREAM_THINK_DELTA && instruction.value.kind === "string") {
+    if (
+      instruction.opcode === Opcode.STREAM_THINK_DELTA &&
+      instruction.value.kind === "string"
+    ) {
       onThinking(instruction.value.value);
-    } else if (instruction.opcode === Opcode.RESP_DONE || instruction.opcode === Opcode.STREAM_END) {
+    } else if (instruction.opcode === Opcode.STREAM_DELTA) {
+      onBody(instruction.value.kind === "string" ? instruction.value.value : "");
+      visible.push(instruction);
+    } else if (
+      instruction.opcode === Opcode.RESP_DONE ||
+      instruction.opcode === Opcode.STREAM_END
+    ) {
       ending.push(instruction);
     } else {
       visible.push(instruction);
     }
   }
-  if (ending.length > 0) terminal.push({ code: ending, buffers: chunk.buffers });
+  if (ending.length > 0)
+    terminal.push({ code: ending, buffers: chunk.buffers });
   return { code: visible, buffers: chunk.buffers };
 }
 
 function thinkingChunk(text: string): Program {
   return {
-    code: [{ opcode: Opcode.STREAM_THINK_DELTA, value: { kind: "string", value: text } }],
+    code: [
+      {
+        opcode: Opcode.STREAM_THINK_DELTA,
+        value: { kind: "string", value: `${text} ` },
+      },
+    ],
     buffers: [],
   };
 }

package/test/collapsed-reasoner.test.ts

@@ -1,6 +1,7 @@
 import {
   appendAssistantMessage,
   appendInstructions,
+  appendUserMessage,
   createProgram,
   delta,
   extractContentText,
@@ -15,7 +16,7 @@ import { createCollapsedReasoner } from "../src/managed/collapsed-reasoner.ts";
 import type { Executor, ExecutorContext } from "../src/types.ts";
 
 describe("createCollapsedReasoner", () => {
-  it("replaces completed raw reasoning with a forced summary", async () => {
+  it("does not append a summary after completed body content", async () => {
     let summaryRequest: Program | undefined;
     const executor = createCollapsedReasoner(
       fromExecute(async () => withThinking("answer", "private reasoning")),
@@ -28,32 +29,139 @@ describe("createCollapsedReasoner", () => {
     const result = await executor.execute(createProgram(), context());
 
     expect(extractContentText(result)).toBe("answer");
-    expect(extractThinkingText(result)).toBe("Working through it.");
-    expect(new ProgramView(summaryRequest!).messages.at(-1)?.text).toBe("private reasoning");
+    expect(extractThinkingText(result)).toBe("");
+    expect(summaryRequest).toBeUndefined();
   });
 
-  it("suppresses raw stream deltas, preserves visible chunks, and flushes before the end", async () => {
+  it("flushes raw stream reasoning before the end and adds trailing spacing", async () => {
     const executor = createCollapsedReasoner(
       streaming(async function* () {
         yield delta.start();
         yield delta.thinking("private reasoning");
-        yield delta.text("answer");
         yield delta.end();
       }),
-      fromExecute(async () => appendAssistantMessage(createProgram(), "Checking details.")),
+      fromExecute(async () =>
+        appendAssistantMessage(createProgram(), "Checking details."),
+      ),
     );
 
     const chunks: Program[] = [];
-    for await (const chunk of executor.stream(createProgram(), context())) chunks.push(chunk);
+    for await (const chunk of executor.stream(createProgram(), context()))
+      chunks.push(chunk);
 
-    expect(extractStreamThinking(chunks)).toEqual(["Checking details."]);
-    expect(chunks.map((chunk) => extractStreamText(chunk)).join("")).toBe("answer");
+    expect(extractStreamThinking(chunks)).toEqual(["Checking details. "]);
+    expect(chunks.map((chunk) => extractStreamText(chunk)).join("")).toBe("");
     expect(chunks.at(-1)?.code.map((item) => item.opcode)).toEqual([
       Opcode.RESP_DONE,
       Opcode.STREAM_END,
     ]);
   });
 
+  it("suppresses a closed phase and restarts when reasoning resumes", async () => {
+    const executor = createCollapsedReasoner(
+      streaming(async function* () {
+        yield delta.thinking("first reasoning");
+        yield delta.text("answer");
+        yield delta.thinking("second reasoning");
+        yield delta.end();
+      }),
+      fromExecute(async (request) =>
+        appendAssistantMessage(
+          createProgram(),
+          `Checking ${new ProgramView(request).messages.at(-1)?.text}.`,
+        ),
+      ),
+    );
+
+    const chunks = await collect(executor.stream(createProgram(), context()));
+
+    expect(extractStreamThinking(chunks)).toEqual([
+      "Checking second reasoning. ",
+    ]);
+    expect(chunks.map((chunk) => extractStreamText(chunk)).join("")).toBe(
+      "answer",
+    );
+  });
+
+  it("starts an initial update from the user prompt alongside the reasoner", async () => {
+    let releaseReasoner: (() => void) | undefined;
+    let sawInitialPrompt = false;
+    const executor = createCollapsedReasoner(
+      streaming(async function* () {
+        yield delta.thinking("private reasoning");
+        await new Promise<void>((resolve) => {
+          releaseReasoner = resolve;
+        });
+        yield delta.text("answer");
+        yield delta.end();
+      }),
+      fromExecute(async (request) => {
+        if (
+          new ProgramView(request).messages.at(-1)?.text === "Plan a trip"
+        ) {
+          sawInitialPrompt = true;
+        }
+        return appendAssistantMessage(createProgram(), "I’m mapping this out.");
+      }),
+    );
+    const iterator = executor
+      .stream(appendUserMessage(createProgram(), "Plan a trip"), context())
+      [Symbol.asyncIterator]();
+
+    const first = await iterator.next();
+    expect(sawInitialPrompt).toBe(true);
+    expect(extractStreamThinking([first.value!])).toEqual([
+      "I’m mapping this out. ",
+    ]);
+
+    releaseReasoner?.();
+    await collect({
+      [Symbol.asyncIterator]: () => iterator,
+    });
+  });
+
+  it("does not delay the answer for an invalidated in-flight summary", async () => {
+    vi.useFakeTimers();
+    let releaseSummary: (() => void) | undefined;
+    let summaryStarted: (() => void) | undefined;
+    const executor = createCollapsedReasoner(
+      streaming(async function* () {
+        yield delta.thinking("private reasoning");
+        await new Promise<void>((resolve) => {
+          summaryStarted = resolve;
+        });
+        yield delta.text("answer");
+        yield delta.end();
+      }),
+      fromExecute(async () => {
+        summaryStarted?.();
+        return new Promise<Program>((resolve) => {
+          releaseSummary = () =>
+            resolve(appendAssistantMessage(createProgram(), "Late update."));
+        });
+      }),
+      { interval: 10, forcedInterval: 20 },
+    );
+    const iterator = executor
+      .stream(createProgram(), context())
+      [Symbol.asyncIterator]();
+
+    const answer = iterator.next();
+    await vi.advanceTimersByTimeAsync(10);
+    const chunk = await answer;
+    expect(extractStreamText(chunk.value!)).toBe("answer");
+    expect(
+      (await iterator.next()).value?.code.some(
+        (item: Instruction) => item.opcode === Opcode.STREAM_END,
+      ),
+    ).toBe(true);
+    expect(await iterator.next()).toMatchObject({ done: true });
+
+    releaseSummary?.();
+    await vi.runAllTimersAsync();
+    vi.useRealTimers();
+  });
+
   it("uses elapsed time for periodic summaries and gives a forced tick priority", async () => {
     vi.useFakeTimers();
     let release: (() => void) | undefined;
@@ -66,11 +174,16 @@ describe("createCollapsedReasoner", () => {
         yield delta.end();
       }),
       fromExecute(async (request) =>
-        appendAssistantMessage(createProgram(), `summary:${extractContentText(request)}`),
+        appendAssistantMessage(
+          createProgram(),
+          `summary:${extractContentText(request)}`,
+        ),
       ),
       { interval: 10, forcedInterval: 20 },
     );
-    const iterator = executor.stream(createProgram(), context())[Symbol.asyncIterator]();
+    const iterator = executor
+      .stream(createProgram(), context())
+      [Symbol.asyncIterator]();
 
     const pendingSummary = iterator.next();
     await vi.advanceTimersByTimeAsync(20);
@@ -79,14 +192,25 @@ describe("createCollapsedReasoner", () => {
     const end = await iterator.next();
     vi.useRealTimers();
 
-    expect(extractStreamThinking([summary.value!])).toEqual([expect.stringContaining("first")]);
-    expect(end.value?.code.some((item: Instruction) => item.opcode === Opcode.STREAM_END)).toBe(true);
+    expect(extractStreamThinking([summary.value!])).toEqual([
+      expect.stringMatching(/first\s$/),
+    ]);
+    expect(
+      end.value?.code.some(
+        (item: Instruction) => item.opcode === Opcode.STREAM_END,
+      ),
+    ).toBe(true);
   });
 
   it("validates its timing options and never emits blank summaries", async () => {
-    expect(() => createCollapsedReasoner("reasoner", "summarizer", { interval: 0 })).toThrow(RangeError);
     expect(() =>
-      createCollapsedReasoner("reasoner", "summarizer", { interval: 10, forcedInterval: 9 }),
+      createCollapsedReasoner("reasoner", "summarizer", { interval: 0 }),
+    ).toThrow(RangeError);
+    expect(() =>
+      createCollapsedReasoner("reasoner", "summarizer", {
+        interval: 10,
+        forcedInterval: 9,
+      }),
     ).toThrow(RangeError);
 
     const executor = createCollapsedReasoner(
@@ -97,7 +221,8 @@ describe("createCollapsedReasoner", () => {
       fromExecute(async () => appendAssistantMessage(createProgram(), "   ")),
     );
     const chunks: Program[] = [];
-    for await (const chunk of executor.stream(createProgram(), context())) chunks.push(chunk);
+    for await (const chunk of executor.stream(createProgram(), context()))
+      chunks.push(chunk);
     expect(extractStreamThinking(chunks)).toEqual([]);
   });
 
@@ -109,7 +234,9 @@ describe("createCollapsedReasoner", () => {
       }),
       "summarizer",
     );
-    await expect(collect(brokenSource.stream(createProgram(), context()))).rejects.toBe(sourceFailure);
+    await expect(
+      collect(brokenSource.stream(createProgram(), context())),
+    ).rejects.toBe(sourceFailure);
 
     const summaryFailure = new Error("summary failed");
     const brokenSummary = createCollapsedReasoner(
@@ -121,7 +248,9 @@ describe("createCollapsedReasoner", () => {
         throw summaryFailure;
       }),
     );
-    await expect(collect(brokenSummary.stream(createProgram(), context()))).rejects.toBe(summaryFailure);
+    await expect(
+      collect(brokenSummary.stream(createProgram(), context())),
+    ).rejects.toBe(summaryFailure);
   });
 });
 
@@ -138,7 +267,11 @@ function withThinking(text: string, thinking: string): Program {
 
 function context(): ExecutorContext {
   const ctx: ExecutorContext = {
-    cache: { get: async () => null, put: async () => {}, delete: async () => {} },
+    cache: {
+      get: async () => null,
+      put: async () => {},
+      delete: async () => {},
+    },
     requestId: "request",
     executionId: "execution",
     invoke(executor, request) {
@@ -160,13 +293,19 @@ function fromExecute(execute: Executor["execute"]): Executor {
 }
 
 function streaming(stream: Executor["stream"]): Executor {
-  return { async execute() { return createProgram(); }, stream };
+  return {
+    async execute() {
+      return createProgram();
+    },
+    stream,
+  };
 }
 
 function extractStreamText(chunk: Program): string {
   let text = "";
   for (const item of chunk.code) {
-    if (item.opcode === Opcode.STREAM_DELTA && item.value.kind === "string") text += item.value.value;
+    if (item.opcode === Opcode.STREAM_DELTA && item.value.kind === "string")
+      text += item.value.value;
   }
   return text;
 }
@@ -175,7 +314,10 @@ function extractStreamThinking(chunks: Program[]): string[] {
   const thinking: string[] = [];
   for (const chunk of chunks) {
     for (const item of chunk.code) {
-      if (item.opcode === Opcode.STREAM_THINK_DELTA && item.value.kind === "string") {
+      if (
+        item.opcode === Opcode.STREAM_THINK_DELTA &&
+        item.value.kind === "string"
+      ) {
         thinking.push(item.value.value);
       }
     }