@neutrome/lilsdk 0.3.5 → 0.4.1

package/src/managed/{twoPassExecutor.ts → two-pass.ts}

@@ -1,15 +1,16 @@
 import {
   callData,
   contentText,
+  createProgram,
   deltaText,
   finishReason,
   hasToolDelta,
   lastMessageRole,
-  setModel,
   type Program,
 } from "@neutrome/lil-engine";
 import { streamReasoningDelta } from "../output.ts";
-import type { Executor, ExecutorContext, InvokeOptions } from "../types.ts";
+import { completeStream, streamStage } from "../stream/stages.ts";
+import type { Executor, ExecutorContext, ExecutorInput } from "../types.ts";
 import {
   appendInternalDraft,
   buildDraftRequest,
@@ -34,41 +35,15 @@ export {
   INTERNAL_DRAFT_TOOL_NAME,
 };
 
-export type ModelExecutor = string | Executor;
-
 export type TwoPassExecutorOptions = TwoPassRequestOptions & {
-  draftModel: ModelExecutor;
-  finalModel: ModelExecutor;
+  draft: ExecutorInput;
+  final: ExecutorInput;
   resolveDraftSettings?: TwoPassSettingsResolver;
   resolveFinalSettings?: TwoPassSettingsResolver;
   reasoningIntro?: string;
   reasoningSeparator?: string;
 };
 
-export function invokeExecutor(
-  ctx: ExecutorContext,
-  request: Program,
-  executor: ModelExecutor,
-  options?: InvokeOptions,
-): Promise<Program> {
-  return typeof executor === "string"
-    ? ctx.invoke(setModel(request, executor), options)
-    : executor.execute(request, ctx);
-}
-
-export async function* streamExecutor(
-  ctx: ExecutorContext,
-  request: Program,
-  executor: ModelExecutor,
-  options?: InvokeOptions,
-): AsyncIterable<Program> {
-  if (typeof executor === "string") {
-    yield* ctx.invokeStream(setModel(request, executor), options);
-    return;
-  }
-  yield* executor.stream(request, ctx);
-}
-
 export function createTwoPassExecutor(
   options: TwoPassExecutorOptions,
 ): Executor {
@@ -84,14 +59,10 @@ export function createTwoPassExecutor(
       }
       const draftRequest = buildDraftRequest(request, settings.draft);
       if (!settings.final || lastMessageRole(request) === "tool") {
-        return invokeExecutor(ctx, draftRequest, options.draftModel);
+        return ctx.invoke(options.draft, draftRequest);
       }
 
-      const draftResponse = await invokeExecutor(
-        ctx,
-        draftRequest,
-        options.draftModel,
-      );
+      const draftResponse = await ctx.invoke(options.draft, draftRequest);
       if (callData(draftResponse).length > 0) return draftResponse;
 
       return invokeFinal(
@@ -111,17 +82,15 @@ export function createTwoPassExecutor(
       }
       const draftRequest = buildDraftRequest(request, settings.draft);
       if (!settings.final || lastMessageRole(request) === "tool") {
-        yield* streamExecutor(ctx, draftRequest, options.draftModel);
+        yield* ctx.invokeStream(options.draft, draftRequest);
         return;
       }
 
       let transcript = "";
       let emittedReasoning = false;
       let toolMode = false;
-      for await (const chunk of streamExecutor(
-        ctx,
-        draftRequest,
-        options.draftModel,
+      for await (const chunk of streamStage(
+        ctx.invokeStream(options.draft, draftRequest),
       )) {
         if (ctx.signal.aborted) return;
         if (toolMode) {
@@ -143,7 +112,11 @@ export function createTwoPassExecutor(
         yield streamReasoningDelta(text);
       }
 
-      if (toolMode || ctx.signal.aborted) return;
+      if (ctx.signal.aborted) return;
+      if (toolMode) {
+        yield completeStream("tool_calls");
+        return;
+      }
       if (emittedReasoning && reasoningSeparator) {
         yield streamReasoningDelta(reasoningSeparator);
       }
@@ -178,10 +151,9 @@ function invokeFinal(
   settings: TwoPassSettings,
   draft = "",
 ): Promise<Program> {
-  return invokeExecutor(
-    ctx,
+  return ctx.invoke(
+    options.final,
     buildFinalRequest(options, request, settings, draft),
-    options.finalModel,
   );
 }
 
@@ -192,9 +164,8 @@ async function* streamFinal(
   settings: TwoPassSettings,
   draft = "",
 ): AsyncIterable<Program> {
-  yield* streamExecutor(
-    ctx,
+  yield* ctx.invokeStream(
+    options.final,
     buildFinalRequest(options, request, settings, draft),
-    options.finalModel,
   );
 }

package/src/stream/index.ts

@@ -1,6 +1,7 @@
 export type { ObservedExecution, StreamObservationHooks } from "../observe.ts";
 
 export { observeExecutionStream } from "../observe.ts";
+export { completeStream, streamStage } from "./stages.ts";
 export {
   streamReasoningDelta,
   streamTextResponse,

package/src/stream/stages.ts

@@ -0,0 +1,25 @@
+import { createProgram, Opcode, type Program } from "@neutrome/lil-engine";
+
+/** Streams one stage without allowing it to complete the enclosing stream. */
+export async function* streamStage(
+  source: AsyncIterable<Program>,
+): AsyncGenerator<Program> {
+  for await (const chunk of source) {
+    const code = chunk.code.filter(
+      (instruction) =>
+        instruction.opcode !== Opcode.RESP_DONE &&
+        instruction.opcode !== Opcode.STREAM_END,
+    );
+    if (code.length === 0) continue;
+    yield code.length === chunk.code.length ? chunk : { ...chunk, code };
+  }
+}
+
+export function completeStream(reason = "stop"): Program {
+  return createProgram({
+    code: [
+      { opcode: Opcode.RESP_DONE, value: { kind: "string", value: reason } },
+      { opcode: Opcode.STREAM_END, value: { kind: "none" } },
+    ],
+  });
+}

package/src/tools.ts

@@ -10,7 +10,12 @@ import {
   type StreamToolDelta,
 } from "@neutrome/lil-engine";
 import { appendToolInteraction } from "./synthetic/index.ts";
-import { type Executor, type ExecutorContext, type Tool } from "./types.ts";
+import {
+  type Executor,
+  type ExecutorContext,
+  type ExecutorInput,
+  type Tool,
+} from "./types.ts";
 import {
   buildCallExecutor,
   buildToolAugmenter,
@@ -176,7 +181,7 @@ async function* streamToolLoop(
 
 export function connectTools(
   tools: Tool[],
-  inner: Executor,
+  inner: ExecutorInput,
   options: WithToolsOptions = {},
 ): Executor {
   const maxIterations = options.maxIterations ?? DEFAULT_MAX_ITERATIONS;
@@ -192,7 +197,7 @@ export function connectTools(
       );
 
       while (canRunToolLoop(state, maxIterations)) {
-        const response = await inner.execute(state.request, ctx);
+        const response = await ctx.invoke(inner, state.request);
         const calls = callData(response);
         const decision = decideToolLoop(calls, toolMap);
         if (decision.kind !== "continue") return response;
@@ -205,7 +210,7 @@ export function connectTools(
         );
       }
 
-      return inner.execute(state.request, ctx);
+      return ctx.invoke(inner, state.request);
     },
 
     async *stream(request, ctx) {
@@ -216,7 +221,7 @@ export function connectTools(
         executeConnectedCalls,
         request,
         ctx,
-        (req) => inner.stream(req, ctx),
+        (req) => ctx.invokeStream(inner, req),
       );
     },
   };

package/src/types.ts

@@ -8,20 +8,6 @@ export type TransformCapability =
   | "drop_content"
   | "provider_extension";
 
-export type ExecutionTarget =
-  | {
-      kind: "provider";
-      provider?: string;
-      model: string;
-      transforms?: string[];
-    }
-  | {
-      kind: "executor";
-      executorId: string;
-      alias: string;
-      transforms?: string[];
-    };
-
 export type ExecutionEvent = {
   kind: string;
   requestId: string;
@@ -37,40 +23,40 @@ export type ExecutionEventInput = Omit<ExecutionEvent, "timestamp"> & {
   timestamp?: string;
 };
 
-export type InvokeOptions = {
-  target?: ExecutionTarget;
-  requestId?: string;
-  executionId?: string;
-  parentExecutionId?: string;
+export type CachePutOptions = {
+  expiration?: number;
+  expirationTtl?: number;
+};
+
+export type Cache = {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options?: CachePutOptions): Promise<void>;
+  delete(key: string): Promise<void>;
 };
 
-export type TransformContext = {
-  invoke(request: Program, options?: InvokeOptions): Promise<Program>;
+type RuntimeContext = {
+  cache: Cache;
+  invoke(executor: ExecutorInput, request: Program): Promise<Program>;
   invokeStream(
+    executor: ExecutorInput,
     request: Program,
-    options?: InvokeOptions,
   ): AsyncIterable<Program>;
   observe(event: ExecutionEvent): void;
   signal: AbortSignal;
 };
 
+export type TransformContext = RuntimeContext;
+
 export type ProgramTransform = {
   name: string;
   capabilities: TransformCapability[];
   apply(program: Program, ctx: TransformContext): Program | Promise<Program>;
 };
 
-export type ExecutorContext = {
+export type ExecutorContext = RuntimeContext & {
   requestId: string;
   executionId: string;
   parentExecutionId?: string;
-  invoke(request: Program, options?: InvokeOptions): Promise<Program>;
-  invokeStream(
-    request: Program,
-    options?: InvokeOptions,
-  ): AsyncIterable<Program>;
-  observe(event: ExecutionEvent): void;
-  signal: AbortSignal;
 };
 
 export type Executor = {
@@ -78,6 +64,8 @@ export type Executor = {
   stream(request: Program, ctx: ExecutorContext): AsyncIterable<Program>;
 };
 
+export type ExecutorInput = string | Executor;
+
 export type Tool = {
   name: string;
   description: string;

package/test/lilsdk-ts.test.ts

@@ -1,10 +1,15 @@
 import {
   contentText,
+  createProgram,
+  deltaText,
   emitChatCompletionsRequest,
   emitChatCompletionsStreamChunk,
   getModel,
   parseChatCompletionsRequest,
   parseChatCompletionsStreamChunk,
+  programAttachments,
+  viewProgram,
+  setModel,
   Opcode,
   type Program,
 } from "@neutrome/lil-engine";
@@ -31,16 +36,66 @@ import { createGoalExecutor, fallback, retry } from "../src/loops/index.ts";
 import {
   appendInternalDraft,
   createTwoPassExecutor,
-  invokeExecutor,
   INTERNAL_DRAFT_TOOL_NAME,
-  streamExecutor,
-} from "../src/managed/twoPassExecutor.ts";
+} from "../src/managed/two-pass.ts";
+import { createAttachmentToTextExecutor } from "../src/managed/attachment-to-text.ts";
 import type { Executor, ExecutorContext, OutputSink } from "../src/types.ts";
 
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
 describe("@neutrome/lilsdk", () => {
+  it("describes the latest attachment and removes it before the inner executor", async () => {
+    const request = parseChatCompletionsRequest(
+      encoder.encode(
+        JSON.stringify({
+          messages: [
+            {
+              role: "user",
+              content: [
+                { type: "text", text: "What is this?" },
+                {
+                  type: "image_url",
+                  image_url: { url: "data:image/png;base64,aGVsbG8=" },
+                },
+              ],
+            },
+          ],
+        }),
+      ),
+    );
+    let innerRequest: Program | undefined;
+    const executor = createAttachmentToTextExecutor(
+      {
+        async execute(value) {
+          innerRequest = value;
+          return value;
+        },
+        async *stream(value) {
+          yield value;
+        },
+      },
+      [
+        {
+          mimeTypes: ["image/*"],
+          executor: {
+            async execute() {
+              return appendAssistantMessage(
+                { code: [], buffers: [] },
+                "A tiny image.",
+              );
+            },
+            async *stream() {},
+          },
+        },
+      ],
+    );
+    await executor.execute(request, buildExecutorContext());
+    expect(programAttachments(innerRequest!)).toHaveLength(0);
+    expect(
+      viewProgram(innerRequest!).messages.at(-1)?.toolResult?.text,
+    ).toContain("The original binary media is not present in this context.");
+  });
   it("provides clone-safe structural primitives", () => {
     const needle = {
       opcode: Opcode.MSG_START,
@@ -197,7 +252,7 @@ describe("@neutrome/lilsdk", () => {
     );
     const seen: Program[] = [];
     const ctx = buildExecutorContext({
-      async invoke(program) {
+      async invoke(_executor, program) {
         seen.push(program);
         if (seen.length === 1) {
           return appendAssistantMessage(
@@ -216,8 +271,8 @@ describe("@neutrome/lilsdk", () => {
     });
 
     const executor = createTwoPassExecutor({
-      draftModel: "smart-model",
-      finalModel: "base-model",
+      draft: "smart-model",
+      final: "base-model",
       resolveFinalSettings: () => ({
         reasoningLevel: "high",
         systemPrompt: "system prompt",
@@ -265,7 +320,7 @@ describe("@neutrome/lilsdk", () => {
     );
     const seen: Program[] = [];
     const ctx = buildExecutorContext({
-      async invoke(program) {
+      async invoke(_executor, program) {
         seen.push(program);
         return appendAssistantMessage(
           { code: [], buffers: [] },
@@ -278,8 +333,8 @@ describe("@neutrome/lilsdk", () => {
     });
 
     const executor = createTwoPassExecutor({
-      draftModel: "smart-model",
-      finalModel: "base-model",
+      draft: "smart-model",
+      final: "base-model",
       resolveDraftSettings: () => ({ systemPrompt: "draft system" }),
     });
 
@@ -295,17 +350,17 @@ describe("@neutrome/lilsdk", () => {
     ]);
   });
 
-  it("invokes and streams string or custom executors", async () => {
+  it("composes model strings and custom executors", async () => {
     const calls: Array<{ model: string; streaming: boolean }> = [];
     const ctx = buildExecutorContext({
-      async invoke(program) {
+      async invoke(_executor, program) {
         calls.push({ model: getModel(program) ?? "", streaming: false });
         return appendAssistantMessage(
           { code: [], buffers: [] },
           "model answer",
         );
       },
-      async *invokeStream(program) {
+      async *invokeStream(_executor, program) {
         calls.push({ model: getModel(program) ?? "", streaming: true });
         yield parseChatCompletionsStreamChunk(
           encoder.encode(
@@ -327,9 +382,9 @@ describe("@neutrome/lilsdk", () => {
         }),
       ),
     );
-    const first = await invokeExecutor(ctx, request, "smart-model");
+    const first = await ctx.invoke("smart-model", request);
     const chunks: Program[] = [];
-    for await (const chunk of streamExecutor(ctx, request, "base-model")) {
+    for await (const chunk of ctx.invokeStream("base-model", request)) {
       chunks.push(chunk);
     }
 
@@ -346,12 +401,12 @@ describe("@neutrome/lilsdk", () => {
     const customExecutor = executorFromExecute(async () =>
       appendAssistantMessage({ code: [], buffers: [] }, "custom answer"),
     );
-    const custom = await invokeExecutor(ctx, request, customExecutor);
+    const custom = await ctx.invoke(customExecutor, request);
     expect(contentText(custom)).toBe("custom answer");
 
     const twoPass = createTwoPassExecutor({
-      draftModel: customExecutor,
-      finalModel: customExecutor,
+      draft: customExecutor,
+      final: customExecutor,
     });
     expect(contentText(await twoPass.execute(request, ctx))).toBe(
       "custom answer",
@@ -369,7 +424,7 @@ describe("@neutrome/lilsdk", () => {
     );
     const seen: Program[] = [];
     const ctx = buildExecutorContext({
-      async invoke(program) {
+      async invoke(_executor, program) {
         seen.push(program);
         return appendAssistantMessage(
           { code: [], buffers: [] },
@@ -382,8 +437,8 @@ describe("@neutrome/lilsdk", () => {
     });
 
     const executor = createTwoPassExecutor({
-      draftModel: "smart-model",
-      finalModel: "base-model",
+      draft: "smart-model",
+      final: "base-model",
       maxTotalContextLength: 10,
       resolveDraftSettings: () => ({ systemPrompt: "draft" }),
     });
@@ -397,8 +452,8 @@ describe("@neutrome/lilsdk", () => {
     let receivedRequest: Program | undefined;
     let receivedContext: ExecutorContext | undefined;
     const directFinal = createTwoPassExecutor({
-      draftModel: "unused",
-      finalModel: "base-model",
+      draft: "unused",
+      final: "base-model",
       resolveDraftSettings: (incomingRequest, incomingContext) => {
         receivedRequest = incomingRequest;
         receivedContext = incomingContext;
@@ -411,14 +466,55 @@ describe("@neutrome/lilsdk", () => {
     expect(receivedContext).toBe(ctx);
 
     const draftOnly = createTwoPassExecutor({
-      draftModel: "smart-model",
-      finalModel: "unused",
+      draft: "smart-model",
+      final: "unused",
       resolveFinalSettings: () => null,
     });
     await draftOnly.execute(request, ctx);
     expect(getModel(seen.at(-1)!)).toBe("smart-model");
   });
 
+  it("keeps two-pass drafts inside the final stream", async () => {
+    const executor = createTwoPassExecutor({
+      draft: "draft",
+      final: "final",
+    });
+    const ctx = buildExecutorContext({
+      async invoke() {
+        throw new Error("non-streaming path is not used in this test");
+      },
+      async *invokeStream(executor) {
+        const text = executor === "draft" ? "draft" : "final";
+        yield createProgram({
+          code: [
+            {
+              opcode: Opcode.STREAM_DELTA,
+              value: { kind: "string", value: text },
+            },
+            {
+              opcode: Opcode.RESP_DONE,
+              value: { kind: "string", value: "stop" },
+            },
+            { opcode: Opcode.STREAM_END, value: { kind: "none" } },
+          ],
+        });
+      },
+    });
+
+    const chunks: Program[] = [];
+    for await (const chunk of executor.stream({ code: [], buffers: [] }, ctx)) {
+      chunks.push(chunk);
+    }
+    const opcodes = chunks.flatMap((chunk) =>
+      chunk.code.map((instruction) => instruction.opcode),
+    );
+
+    expect(
+      opcodes.filter((opcode) => opcode === Opcode.STREAM_END),
+    ).toHaveLength(1);
+    expect(chunks.map(deltaText).filter(Boolean)).toContain("final");
+  });
+
   it("writes reasoning helpers to a sink", async () => {
     const emitted: string[] = [];
     const sink: OutputSink = {
@@ -582,7 +678,7 @@ describe("@neutrome/lilsdk", () => {
       chunks.push(chunk);
     }
 
-    expect(chunks.map(contentText)).toEqual([
+    expect(chunks.map(contentText).filter(Boolean)).toEqual([
       "answer 1",
       "retry",
       "answer 2",
@@ -590,6 +686,61 @@ describe("@neutrome/lilsdk", () => {
     ]);
   });
 
+  it("keeps goal stage completions inside one stream", async () => {
+    let attempt = 0;
+    const stage = (text: string) =>
+      streamingExecutor(async function* () {
+        yield createProgram({
+          code: [
+            {
+              opcode: Opcode.STREAM_DELTA,
+              value: { kind: "string", value: text },
+            },
+            {
+              opcode: Opcode.RESP_DONE,
+              value: { kind: "string", value: "stop" },
+            },
+            { opcode: Opcode.STREAM_END, value: { kind: "none" } },
+          ],
+        });
+      });
+    const executor = createGoalExecutor({
+      draft: streamingExecutor(async function* () {
+        attempt += 1;
+        yield* stage(`answer ${attempt}`).stream(
+          { code: [], buffers: [] },
+          buildExecutorContext(),
+        );
+      }),
+      review: streamingExecutor(async function* () {
+        yield* stage("review").stream(
+          { code: [], buffers: [] },
+          buildExecutorContext(),
+        );
+      }),
+      satisfied: () => attempt === 2,
+      refine: (request) => request,
+    });
+
+    const chunks: Program[] = [];
+    for await (const chunk of executor.stream(
+      { code: [], buffers: [] },
+      buildExecutorContext(),
+    )) {
+      chunks.push(chunk);
+    }
+
+    const opcodes = chunks.flatMap((chunk) =>
+      chunk.code.map((instruction) => instruction.opcode),
+    );
+    expect(
+      opcodes.filter((opcode) => opcode === Opcode.RESP_DONE),
+    ).toHaveLength(1);
+    expect(
+      opcodes.filter((opcode) => opcode === Opcode.STREAM_END),
+    ).toHaveLength(1);
+  });
+
   it("uses streamed text as the next goal stage's response", async () => {
     let reviewedAnswer = "";
     const executor = createGoalExecutor({
@@ -621,24 +772,44 @@ describe("@neutrome/lilsdk", () => {
 
 function buildExecutorContext(
   impl: Pick<ExecutorContext, "invoke" | "invokeStream"> = {
-    async invoke(program) {
-      return program;
+    async invoke(_executor, request) {
+      return request;
     },
-    async *invokeStream(program) {
-      yield program;
+    async *invokeStream(_executor, request) {
+      yield request;
     },
   },
 ): ExecutorContext {
-  return {
+  const context: ExecutorContext = {
+    cache: testCache,
     requestId: "req_test",
     executionId: "exec_test",
-    invoke: impl.invoke,
-    invokeStream: impl.invokeStream,
+    invoke(executor, request) {
+      return typeof executor === "string"
+        ? impl.invoke(executor, setModel(request, executor))
+        : executor.execute(request, context);
+    },
+    async *invokeStream(executor, request) {
+      if (typeof executor === "string") {
+        yield* impl.invokeStream(executor, setModel(request, executor));
+        return;
+      }
+      yield* executor.stream(request, context);
+    },
     observe: () => {},
     signal: new AbortController().signal,
   };
+  return context;
 }
 
+const testCache: ExecutorContext["cache"] = {
+  async get() {
+    return null;
+  },
+  async put() {},
+  async delete() {},
+};
+
 function executorFromExecute(execute: Executor["execute"]): Executor {
   return {
     execute,