@neutrome/lilsdk 0.4.5 → 0.5.0

package/test/tools.test.ts

@@ -1,12 +1,13 @@
 import { describe, expect, it } from "vitest";
 import {
-  callData,
   createProgram,
+  extractToolCalls,
   Opcode,
+  ProgramView,
   type Instruction,
   type Program,
 } from "@neutrome/lil-engine";
-import { connectTools, ToolArgumentsError } from "../src/tools.ts";
+import { createToolsExecutor } from "../src/tools.ts";
 import type { ExecutorContext, Tool } from "../src/types.ts";
 
 function buildToolCallResponse(
@@ -63,7 +64,7 @@ const calculatorTool: Tool = {
   },
 };
 
-describe("connectTools", () => {
+describe("createToolsExecutor", () => {
   it("passes the executor cache to connected tools", async () => {
     let callCount = 0;
     const cache = {
@@ -82,7 +83,7 @@ describe("connectTools", () => {
         return (await ctx.cache.get("tool-key")) ?? "missing";
       },
     };
-    const executor = connectTools([tool], "test-model");
+    const executor = createToolsExecutor("test-model", [tool]);
     const ctx = buildCtx({
       async invoke() {
         callCount += 1;
@@ -104,7 +105,7 @@ describe("connectTools", () => {
   });
 
   it("passes through when LLM returns no tool calls", async () => {
-    const executor = connectTools([calculatorTool], "test-model");
+    const executor = createToolsExecutor("test-model", [calculatorTool]);
 
     const request = createProgram({
       code: [
@@ -135,7 +136,7 @@ describe("connectTools", () => {
   });
 
   it("executes connected tool and loops until text response", async () => {
-    const executor = connectTools([calculatorTool], "test-model");
+    const executor = createToolsExecutor("test-model", [calculatorTool]);
 
     let callCount = 0;
     const request = createProgram({
@@ -173,22 +174,69 @@ describe("connectTools", () => {
     expect(hasAnswer).toBe(true);
   });
 
-  it("rejects malformed connected-tool arguments", async () => {
-    const executor = connectTools([calculatorTool], "test-model");
+  it("returns malformed connected-tool arguments to the model", async () => {
+    const executor = createToolsExecutor("test-model", [calculatorTool]);
+    let retryRequest: Program | undefined;
+    let invocations = 0;
     const ctx = buildCtx({
-      async invoke() {
-        return buildToolCallResponse([
-          { id: "call_1", name: "calculator", args: "{not json}" },
-        ]);
+      async invoke(_executor, request) {
+        invocations += 1;
+        if (invocations === 1) {
+          return buildToolCallResponse([
+            { id: "call_1", name: "calculator", args: "{not json}" },
+          ]);
+        }
+        retryRequest = request;
+        return buildTextResponse("I need valid calculator arguments.");
       },
       async *invokeStream() {
         return;
       },
     });
 
-    await expect(executor.execute(createProgram(), ctx)).rejects.toBeInstanceOf(
-      ToolArgumentsError,
+    const result = await executor.execute(createProgram(), ctx);
+
+    expect(invocations).toBe(2);
+    expect(
+      new ProgramView(retryRequest!).messages.at(-1)?.toolResult?.text,
+    ).toBe(
+      'Tool "calculator" failed: Tool "calculator" received invalid JSON object arguments',
     );
+    expect(extractToolCalls(result)).toHaveLength(0);
+  });
+
+  it("returns thrown connected-tool errors to the model", async () => {
+    const failingTool: Tool = {
+      ...calculatorTool,
+      async execute() {
+        throw new Error("Calculator service is unavailable");
+      },
+    };
+    const executor = createToolsExecutor("test-model", [failingTool]);
+    let retryRequest: Program | undefined;
+    let invocations = 0;
+    const ctx = buildCtx({
+      async invoke(_executor, request) {
+        invocations += 1;
+        if (invocations === 1) {
+          return buildToolCallResponse([
+            { id: "call_1", name: "calculator", args: '{"expr":"2+2"}' },
+          ]);
+        }
+        retryRequest = request;
+        return buildTextResponse("I cannot calculate that right now.");
+      },
+      async *invokeStream() {
+        return;
+      },
+    });
+
+    await executor.execute(createProgram(), ctx);
+
+    expect(invocations).toBe(2);
+    expect(
+      new ProgramView(retryRequest!).messages.at(-1)?.toolResult?.text,
+    ).toBe('Tool "calculator" failed: Calculator service is unavailable');
   });
 
   it("handles multiple tool calls in single response (parallel execution)", async () => {
@@ -203,7 +251,7 @@ describe("connectTools", () => {
         return `value_of_${key}`;
       },
     };
-    const executor = connectTools([multiTool], "test-model");
+    const executor = createToolsExecutor("test-model", [multiTool]);
 
     let callCount = 0;
     const request = createProgram();
@@ -230,7 +278,7 @@ describe("connectTools", () => {
   });
 
   it("returns immediately when outer (non-connected) tool calls are present", async () => {
-    const executor = connectTools([calculatorTool], "test-model");
+    const executor = createToolsExecutor("test-model", [calculatorTool]);
 
     const request = createProgram();
     const ctx = buildCtx({
@@ -252,17 +300,17 @@ describe("connectTools", () => {
         return calculatorTool.execute(args, ctx);
       },
     };
-    const guardedExecutor = connectTools([tool], "test-model");
+    const guardedExecutor = createToolsExecutor("test-model", [tool]);
     const result = await guardedExecutor.execute(request, ctx);
 
-    const calls = callData(result);
+    const calls = extractToolCalls(result);
     expect(calls).toHaveLength(2);
     expect(calls.some((c) => c.name === "external_tool")).toBe(true);
     expect(executions).toBe(0);
   });
 
   it("respects maxIterations", async () => {
-    const executor = connectTools([calculatorTool], "test-model", {
+    const executor = createToolsExecutor("test-model", [calculatorTool], {
       maxIterations: 2,
     });
 
@@ -290,7 +338,7 @@ describe("connectTools", () => {
   });
 
   it("streams final response after tool loop completes", async () => {
-    const executor = connectTools([calculatorTool], "test-model");
+    const executor = createToolsExecutor("test-model", [calculatorTool]);
 
     let callCount = 0;
     const request = createProgram();
@@ -349,7 +397,7 @@ describe("connectTools", () => {
         return "4";
       },
     };
-    const executor = connectTools([tool], "test-model");
+    const executor = createToolsExecutor("test-model", [tool]);
     let invocation = 0;
     const ctx = buildCtx({
       async invoke() {

package/src/managed/two-pass-request.ts

@@ -1,164 +0,0 @@
-import {
-  appendInstructions,
-  contentText,
-  insertBefore,
-  messageText,
-  messages,
-  removeRange,
-  type Program,
-} from "@neutrome/lil-engine";
-import { Opcode } from "@neutrome/lil-engine";
-import {
-  appendToolInteraction,
-  makeMessage,
-  prependSystemPrompt,
-} from "../synthetic/index.ts";
-import type { ExecutorContext } from "../types.ts";
-
-export const INTERNAL_DRAFT_TOOL_NAME = "knowledge";
-export const INTERNAL_DRAFT_CALL_ID = "knowledge_0";
-
-export type InternalDraft =
-  | string
-  | readonly string[]
-  | readonly { text: string }[];
-
-export type TwoPassSettings = {
-  reasoningLevel?: string;
-  systemPrompt?: string;
-};
-
-export type TwoPassSettingsResolver = (
-  request: Program,
-  ctx: ExecutorContext,
-) => TwoPassSettings | null | Promise<TwoPassSettings | null>;
-
-export type TwoPassRequestOptions = {
-  maxTotalContextLength?: number;
-  buildFinalRequest?: (request: Program, draft: string) => Program;
-};
-
-export function appendInternalDraft(
-  request: Program,
-  draft: InternalDraft,
-  options: { callId?: string } = {},
-): Program {
-  const callId = options.callId ?? INTERNAL_DRAFT_CALL_ID;
-  const drafts = normalizeDrafts(draft);
-  if (drafts.length === 0) return request;
-  return drafts.reduce(
-    (program, text, index) =>
-      appendToolInteraction(program, {
-        callId: drafts.length === 1 ? callId : `${callId}_${index}`,
-        name: INTERNAL_DRAFT_TOOL_NAME,
-        args: {},
-        result: text,
-      }),
-    request,
-  );
-}
-
-export function buildDraftRequest(
-  request: Program,
-  settings: TwoPassSettings,
-): Program {
-  const withPrompt = settings.systemPrompt
-    ? replaceSystemPrompt(request, settings.systemPrompt)
-    : request;
-  return applySettings(withPrompt, settings);
-}
-
-export function buildFinalRequest(
-  options: TwoPassRequestOptions,
-  request: Program,
-  settings: TwoPassSettings,
-  draft: string,
-): Program {
-  const limitedDraft = limitDraft(options, request, settings, draft);
-  const withDraft = options.buildFinalRequest
-    ? options.buildFinalRequest(request, limitedDraft)
-    : appendInternalDraft(request, limitedDraft);
-  const withPrompt = settings.systemPrompt
-    ? prependSystemPrompt(withDraft, settings.systemPrompt)
-    : withDraft;
-  return applySettings(withPrompt, settings);
-}
-
-export function validateMaxContextLength(value: number | undefined): void {
-  if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
-    throw new Error("maxTotalContextLength must be a non-negative integer");
-  }
-}
-
-function replaceSystemPrompt(request: Program, systemPrompt: string): Program {
-  const systemSpans = messages(request).filter(
-    (span) => span.role === "system",
-  );
-  const previousSystemPrompt = systemSpans
-    .map((span) => messageText(request, span).trim())
-    .filter(Boolean)
-    .join("\n\n");
-  let draft = request;
-  for (const span of systemSpans.slice().reverse()) {
-    draft = removeRange(draft, span.start, span.end);
-  }
-  draft = prependSystemPrompt(draft, systemPrompt);
-  if (!previousSystemPrompt) return draft;
-  const firstNonSystem = messages(draft).find((span) => span.role !== "system");
-  return insertBefore(
-    draft,
-    firstNonSystem?.start ?? draft.code.length,
-    makeMessage("user", previousSystemPrompt).code,
-  );
-}
-
-function applySettings(request: Program, settings: TwoPassSettings): Program {
-  if (!settings.reasoningLevel) return request;
-  return appendInstructions(
-    {
-      ...request,
-      code: request.code.filter(
-        (instruction) => instruction.opcode !== Opcode.SET_REASON_EFFORT,
-      ),
-    },
-    [
-      {
-        opcode: Opcode.SET_REASON_EFFORT,
-        value: { kind: "string", value: settings.reasoningLevel },
-      },
-    ],
-  );
-}
-
-function limitDraft(
-  options: TwoPassRequestOptions,
-  request: Program,
-  settings: TwoPassSettings,
-  draft: string,
-): string {
-  if (options.maxTotalContextLength === undefined) return draft;
-  const base = buildFinalRequestWithoutDraft(options, request, settings);
-  const available = options.maxTotalContextLength - contentText(base).length;
-  return available > 0 ? draft.slice(0, available) : "";
-}
-
-function buildFinalRequestWithoutDraft(
-  options: TwoPassRequestOptions,
-  request: Program,
-  settings: TwoPassSettings,
-): Program {
-  const withDraft = options.buildFinalRequest
-    ? options.buildFinalRequest(request, "")
-    : request;
-  const withPrompt = settings.systemPrompt
-    ? prependSystemPrompt(withDraft, settings.systemPrompt)
-    : withDraft;
-  return applySettings(withPrompt, settings);
-}
-
-function normalizeDrafts(draft: InternalDraft): string[] {
-  const drafts = Array.isArray(draft)
-    ? draft.map((item) => (typeof item === "string" ? item : item.text))
-    : [draft];
-  return drafts.map((text) => text.trim()).filter((text) => text.length > 0);
-}

package/src/managed/two-pass.ts

@@ -1,171 +0,0 @@
-import {
-  callData,
-  contentText,
-  createProgram,
-  deltaText,
-  finishReason,
-  hasToolDelta,
-  lastMessageRole,
-  type Program,
-} from "@neutrome/lil-engine";
-import { streamReasoningDelta } from "../output.ts";
-import { completeStream, streamStage } from "../stream/stages.ts";
-import type { Executor, ExecutorContext, ExecutorInput } from "../types.ts";
-import {
-  appendInternalDraft,
-  buildDraftRequest,
-  buildFinalRequest,
-  INTERNAL_DRAFT_CALL_ID,
-  INTERNAL_DRAFT_TOOL_NAME,
-  validateMaxContextLength,
-  type InternalDraft,
-  type TwoPassRequestOptions,
-  type TwoPassSettings,
-  type TwoPassSettingsResolver,
-} from "./two-pass-request.ts";
-
-export type {
-  InternalDraft,
-  TwoPassSettings,
-  TwoPassSettingsResolver,
-} from "./two-pass-request.ts";
-export {
-  appendInternalDraft,
-  INTERNAL_DRAFT_CALL_ID,
-  INTERNAL_DRAFT_TOOL_NAME,
-};
-
-export type TwoPassExecutorOptions = TwoPassRequestOptions & {
-  draft: ExecutorInput;
-  final: ExecutorInput;
-  resolveDraftSettings?: TwoPassSettingsResolver;
-  resolveFinalSettings?: TwoPassSettingsResolver;
-  reasoningIntro?: string;
-  reasoningSeparator?: string;
-};
-
-export function createTwoPassExecutor(
-  options: TwoPassExecutorOptions,
-): Executor {
-  const reasoningIntro = options.reasoningIntro ?? "Let me think...\n\n";
-  const reasoningSeparator = options.reasoningSeparator ?? "\n\n";
-  validateMaxContextLength(options.maxTotalContextLength);
-
-  return {
-    async execute(request, ctx) {
-      const settings = await resolveSettings(options, request, ctx);
-      if (!settings.draft) {
-        return invokeFinal(options, request, ctx, settings.final!);
-      }
-      const draftRequest = buildDraftRequest(request, settings.draft);
-      if (!settings.final || lastMessageRole(request) === "tool") {
-        return ctx.invoke(options.draft, draftRequest);
-      }
-
-      const draftResponse = await ctx.invoke(options.draft, draftRequest);
-      if (callData(draftResponse).length > 0) return draftResponse;
-
-      return invokeFinal(
-        options,
-        request,
-        ctx,
-        settings.final,
-        contentText(draftResponse),
-      );
-    },
-
-    async *stream(request, ctx) {
-      const settings = await resolveSettings(options, request, ctx);
-      if (!settings.draft) {
-        yield* streamFinal(options, request, ctx, settings.final!);
-        return;
-      }
-      const draftRequest = buildDraftRequest(request, settings.draft);
-      if (!settings.final || lastMessageRole(request) === "tool") {
-        yield* ctx.invokeStream(options.draft, draftRequest);
-        return;
-      }
-
-      let transcript = "";
-      let emittedReasoning = false;
-      let toolMode = false;
-      for await (const chunk of streamStage(
-        ctx.invokeStream(options.draft, draftRequest),
-      )) {
-        if (ctx.signal.aborted) return;
-        if (toolMode) {
-          yield chunk;
-          continue;
-        }
-        if (hasToolDelta(chunk) || finishReason(chunk) === "tool_calls") {
-          toolMode = true;
-          yield chunk;
-          continue;
-        }
-        const text = deltaText(chunk);
-        if (!text) continue;
-        transcript += text;
-        if (!emittedReasoning) {
-          emittedReasoning = true;
-          yield streamReasoningDelta(reasoningIntro);
-        }
-        yield streamReasoningDelta(text);
-      }
-
-      if (ctx.signal.aborted) return;
-      if (toolMode) {
-        yield completeStream("tool_calls");
-        return;
-      }
-      if (emittedReasoning && reasoningSeparator) {
-        yield streamReasoningDelta(reasoningSeparator);
-      }
-      yield* streamFinal(options, request, ctx, settings.final, transcript);
-    },
-  };
-}
-
-async function resolveSettings(
-  options: TwoPassExecutorOptions,
-  request: Program,
-  ctx: ExecutorContext,
-): Promise<{ draft: TwoPassSettings | null; final: TwoPassSettings | null }> {
-  const [draft, final] = await Promise.all([
-    options.resolveDraftSettings
-      ? options.resolveDraftSettings(request, ctx)
-      : {},
-    options.resolveFinalSettings
-      ? options.resolveFinalSettings(request, ctx)
-      : {},
-  ]);
-  if (!draft && !final) {
-    throw new Error("Two-pass executor requires at least one enabled pass");
-  }
-  return { draft, final };
-}
-
-function invokeFinal(
-  options: TwoPassExecutorOptions,
-  request: Program,
-  ctx: ExecutorContext,
-  settings: TwoPassSettings,
-  draft = "",
-): Promise<Program> {
-  return ctx.invoke(
-    options.final,
-    buildFinalRequest(options, request, settings, draft),
-  );
-}
-
-async function* streamFinal(
-  options: TwoPassExecutorOptions,
-  request: Program,
-  ctx: ExecutorContext,
-  settings: TwoPassSettings,
-  draft = "",
-): AsyncIterable<Program> {
-  yield* ctx.invokeStream(
-    options.final,
-    buildFinalRequest(options, request, settings, draft),
-  );
-}

package/src/synthetic/index.ts

@@ -1,134 +0,0 @@
-import {
-  addTool,
-  appendInstructions,
-  createProgram,
-  insertBefore,
-  messages,
-  Opcode,
-  setModel,
-  type Instruction,
-  type Opcode as OpcodeValue,
-  type Program,
-} from "@neutrome/lil-engine";
-
-const encoder = new TextEncoder();
-
-export type TextMessageRole = "system" | "user" | "assistant";
-
-export type ToolInteraction = {
-  callId: string;
-  name: string;
-  args?: unknown;
-  result: unknown;
-};
-
-export function createModelProgram(model: string): Program {
-  return setModel(createProgram(), model);
-}
-
-export function makeMessage(role: TextMessageRole, text: string): Program {
-  return createProgram({ code: buildMessage(role, text) });
-}
-
-export function prependSystemPrompt(program: Program, text: string): Program {
-  const systemMessage = buildMessage("system", text);
-  const spans = messages(program);
-  if (spans.length === 0) {
-    return appendInstructions(program, systemMessage);
-  }
-  const firstSpan = spans[0];
-  if (!firstSpan) return appendInstructions(program, systemMessage);
-  return insertBefore(program, firstSpan.start, systemMessage);
-}
-
-export function appendUserMessage(program: Program, text: string): Program {
-  return appendInstructions(program, buildMessage("user", text));
-}
-
-export function appendAssistantMessage(
-  program: Program,
-  text: string,
-): Program {
-  return appendInstructions(program, buildMessage("assistant", text));
-}
-
-export function makeToolCall(
-  name: string,
-  args: unknown = {},
-  callId: string = crypto.randomUUID(),
-): Program {
-  return createProgram({
-    code: [
-      { opcode: Opcode.MSG_START, value: { kind: "none" } },
-      { opcode: Opcode.ROLE_AST, value: { kind: "none" } },
-      { opcode: Opcode.CALL_START, value: { kind: "string", value: callId } },
-      { opcode: Opcode.CALL_NAME, value: { kind: "string", value: name } },
-      {
-        opcode: Opcode.CALL_ARGS,
-        value: { kind: "json", value: encodeJson(args) },
-      },
-      { opcode: Opcode.CALL_END, value: { kind: "none" } },
-      { opcode: Opcode.MSG_END, value: { kind: "none" } },
-    ],
-  });
-}
-
-export function makeToolResponse(callId: string, result: unknown): Program {
-  return createProgram({ code: buildToolResponse(callId, result) });
-}
-
-export function appendToolInteraction(
-  program: Program,
-  interaction: ToolInteraction,
-): Program {
-  return appendInstructions(program, [
-    ...makeToolCall(
-      interaction.name,
-      interaction.args ?? {},
-      interaction.callId,
-    ).code,
-    ...buildToolResponse(interaction.callId, interaction.result),
-  ]);
-}
-
-function buildMessage(role: TextMessageRole, text: string): Instruction[] {
-  return [
-    { opcode: Opcode.MSG_START, value: { kind: "none" } },
-    { opcode: roleOpcode(role), value: { kind: "none" } },
-    { opcode: Opcode.TXT_CHUNK, value: { kind: "string", value: text } },
-    { opcode: Opcode.MSG_END, value: { kind: "none" } },
-  ];
-}
-
-function buildToolResponse(callId: string, result: unknown): Instruction[] {
-  return [
-    { opcode: Opcode.MSG_START, value: { kind: "none" } },
-    { opcode: Opcode.ROLE_TOOL, value: { kind: "none" } },
-    { opcode: Opcode.RESULT_START, value: { kind: "string", value: callId } },
-    {
-      opcode: Opcode.RESULT_DATA,
-      value: { kind: "string", value: stringifyResult(result) },
-    },
-    { opcode: Opcode.RESULT_END, value: { kind: "none" } },
-    { opcode: Opcode.MSG_END, value: { kind: "none" } },
-  ];
-}
-
-function roleOpcode(role: TextMessageRole): OpcodeValue {
-  switch (role) {
-    case "system":
-      return Opcode.ROLE_SYS;
-    case "user":
-      return Opcode.ROLE_USR;
-    case "assistant":
-      return Opcode.ROLE_AST;
-  }
-}
-
-function encodeJson(value: unknown): Uint8Array {
-  return encoder.encode(JSON.stringify(value));
-}
-
-function stringifyResult(result: unknown): string {
-  return typeof result === "string" ? result : JSON.stringify(result);
-}