@neutrome/lilsdk 0.4.4 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neutrome/lilsdk",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -13,7 +13,7 @@
     "./managed": "./src/managed/index.ts"
   },
   "dependencies": {
-    "@neutrome/lil-engine": "0.4.3"
+    "@neutrome/lil-engine": "0.4.6"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",
@@ -22,6 +22,7 @@
   },
   "scripts": {
     "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "npm:publish": "pnpm publish --no-git-checks"
   }
 }

package/src/managed/capabilities.ts

@@ -20,6 +20,7 @@ const encoder = new TextEncoder();
 export type CapabilitiesExecutorOptions = {
   enabledIterations?: number;
   cacheKey?: (ctx: ExecutorContext) => string;
+  skipPrefixes?: readonly string[];
 };
 
 type CapabilitySelection = { toolName: string; remaining: number };
@@ -30,16 +31,22 @@ export function createCapabilitiesExecutor(
 ): Executor {
   const enabledIterations = positiveInteger(options.enabledIterations ?? 5);
   const cacheKey = options.cacheKey ?? ((ctx) => ctx.requestId);
+  const skipPrefixes = options.skipPrefixes ?? [];
 
   return {
     async execute(request, ctx) {
       const tools = viewProgram(request).tools;
       if (tools.length === 0) return ctx.invoke(inner, request);
 
+      const managedTools = tools.filter(
+        (tool) => !skipPrefixes.some((prefix) => tool.name.startsWith(prefix)),
+      );
+      if (managedTools.length === 0) return ctx.invoke(inner, request);
+
       const key = selectionKey(cacheKey(ctx));
-      await discardMissingSelection(ctx, key, tools);
-      return connectCapabilities(inner, tools, key, enabledIterations).execute(
-        withoutTools(request),
+      await discardMissingSelection(ctx, key, managedTools);
+      return connectCapabilities(inner, managedTools, key, enabledIterations).execute(
+        withoutManagedTools(request, managedTools),
         ctx,
       );
     },
@@ -51,10 +58,18 @@ export function createCapabilitiesExecutor(
         return;
       }
 
+      const managedTools = tools.filter(
+        (tool) => !skipPrefixes.some((prefix) => tool.name.startsWith(prefix)),
+      );
+      if (managedTools.length === 0) {
+        yield* ctx.invokeStream(inner, request);
+        return;
+      }
+
       const key = selectionKey(cacheKey(ctx));
-      await discardMissingSelection(ctx, key, tools);
-      yield* connectCapabilities(inner, tools, key, enabledIterations).stream(
-        withoutTools(request),
+      await discardMissingSelection(ctx, key, managedTools);
+      yield* connectCapabilities(inner, managedTools, key, enabledIterations).stream(
+        withoutManagedTools(request, managedTools),
         ctx,
       );
     },
@@ -153,9 +168,14 @@ async function discardMissingSelection(
   }
 }
 
-function withoutTools(request: Program): Program {
+function withoutManagedTools(
+  request: Program,
+  managedTools: readonly ProgramTool[],
+): Program {
+  const managedNames = new Set(managedTools.map((tool) => tool.name));
   const indices: number[] = [];
   for (const definition of toolDefinitions(request)) {
+    if (!definition.name || !managedNames.has(definition.name)) continue;
     for (let index = definition.start; index <= definition.end; index += 1) {
       indices.push(index);
     }

package/src/managed/index.ts

@@ -5,17 +5,3 @@ export type {
   AttachmentReaderRule,
   AttachmentToTextOptions,
 } from "./attachment-to-text.ts";
-
-export {
-  appendInternalDraft,
-  createTwoPassExecutor,
-  INTERNAL_DRAFT_CALL_ID,
-  INTERNAL_DRAFT_TOOL_NAME,
-} from "./two-pass.ts";
-
-export type {
-  InternalDraft,
-  TwoPassExecutorOptions,
-  TwoPassSettings,
-  TwoPassSettingsResolver,
-} from "./two-pass.ts";

package/src/tools-support.ts

@@ -7,7 +7,12 @@ import {
 } from "./types.ts";
 
 export type ToolCall = { id: string; name: string; args: string };
-export type ToolExecution = ToolCall & { result: string };
+export type ToolExecution = {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+  result: string;
+};
 
 export class ToolArgumentsError extends Error {
   constructor(
@@ -49,37 +54,52 @@ export function buildCallExecutor(toolMap: ReadonlyMap<string, Tool>) {
   ): Promise<ToolExecution[]> =>
     Promise.all(
       calls.map(async (call) => {
-        const tool = toolMap.get(call.name);
-        if (!tool) {
-          throw new Error(`No tool is registered for call "${call.name}"`);
-        }
         const startedMs = Date.now();
-        const result = await tool.execute(
-          parseToolArguments(call.name, call.args),
-          ctx,
-        );
-        const finishedMs = Date.now();
-        ctx.observe(
-          createExecutionEvent({
-            kind: "tool.executed",
-            requestId: ctx.requestId,
-            executionId: `tool_${call.id || crypto.randomUUID()}`,
-            parentExecutionId: ctx.executionId,
-            data: {
-              toolName: call.name,
-              toolCallId: call.id,
-              startedAt: new Date(startedMs).toISOString(),
-              finishedAt: new Date(finishedMs).toISOString(),
-              durationMs: finishedMs - startedMs,
-              lilText: toolTrace(call, result),
-            },
-          }),
-        );
-        return { ...call, result };
+        try {
+          const tool = toolMap.get(call.name);
+          if (!tool) {
+            throw new Error(`No tool is registered for call "${call.name}"`);
+          }
+          const args = parseToolArguments(call.name, call.args);
+          const result = await tool.execute(args, ctx);
+          observeToolExecution(ctx, call, startedMs, result);
+          return { id: call.id, name: call.name, args, result };
+        } catch (error) {
+          const result = toolFailureResult(call.name, error);
+          observeToolExecution(ctx, call, startedMs, result, error);
+          return { id: call.id, name: call.name, args: {}, result };
+        }
       }),
     );
 }
 
+function observeToolExecution(
+  ctx: ExecutorContext,
+  call: ToolCall,
+  startedMs: number,
+  result: string,
+  error?: unknown,
+): void {
+  const finishedMs = Date.now();
+  ctx.observe(
+    createExecutionEvent({
+      kind: error ? "tool.failed" : "tool.executed",
+      requestId: ctx.requestId,
+      executionId: `tool_${call.id || crypto.randomUUID()}`,
+      parentExecutionId: ctx.executionId,
+      ...(error instanceof Error ? { errorKind: error.name } : {}),
+      data: {
+        toolName: call.name,
+        toolCallId: call.id,
+        startedAt: new Date(startedMs).toISOString(),
+        finishedAt: new Date(finishedMs).toISOString(),
+        durationMs: finishedMs - startedMs,
+        lilText: toolTrace(call, result),
+      },
+    }),
+  );
+}
+
 export function parseToolArguments(
   toolName: string,
   argumentsText: string,
@@ -106,3 +126,8 @@ function toolTrace(call: ToolCall, result: string): string {
     "RESULT_END",
   ].join("\n");
 }
+
+function toolFailureResult(toolName: string, error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return `Tool "${toolName}" failed: ${message}`;
+}

package/src/tools.ts

@@ -264,7 +264,7 @@ function appendToolResults(
       appendToolInteraction(next, {
         callId: result.id,
         name: result.name,
-        args: parseToolArguments(result.name, result.args),
+        args: result.args,
         result: result.result,
       }),
     request,

package/test/lilsdk-ts.test.ts

@@ -1,10 +1,8 @@
 import {
   contentText,
   createProgram,
-  deltaText,
   emitChatCompletionsRequest,
   emitChatCompletionsStreamChunk,
-  getModel,
   parseChatCompletionsRequest,
   parseChatCompletionsStreamChunk,
   programAttachments,
@@ -33,18 +31,42 @@ import {
   writeReasoning,
 } from "../src/stream/index.ts";
 import { createGoalExecutor, fallback, retry } from "../src/loops/index.ts";
-import {
-  appendInternalDraft,
-  createTwoPassExecutor,
-  INTERNAL_DRAFT_TOOL_NAME,
-} from "../src/managed/two-pass.ts";
 import { createAttachmentToTextExecutor } from "../src/managed/attachment-to-text.ts";
+import { createCapabilitiesExecutor } from "../src/managed/capabilities.ts";
 import type { Executor, ExecutorContext, OutputSink } from "../src/types.ts";
 
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
 describe("@neutrome/lilsdk", () => {
+  it("leaves capability tool prefixes directly available", async () => {
+    const request = parseChatCompletionsRequest(
+      encoder.encode(
+        JSON.stringify({
+          tools: [
+            { type: "function", function: { name: "keep_search" } },
+            { type: "function", function: { name: "managed_weather" } },
+          ],
+        }),
+      ),
+    );
+    let innerRequest: Program | undefined;
+    const executor = createCapabilitiesExecutor(
+      executorFromExecute(async (value) => {
+        innerRequest = value;
+        return value;
+      }),
+      { skipPrefixes: ["keep_"] },
+    );
+
+    await executor.execute(request, buildExecutorContext());
+
+    expect(viewProgram(innerRequest!).tools.map((tool) => tool.name)).toEqual([
+      "keep_search",
+      "learn_capability",
+    ]);
+  });
+
   it("describes the latest attachment and removes it before the inner executor", async () => {
     const request = parseChatCompletionsRequest(
       encoder.encode(
@@ -188,27 +210,6 @@ describe("@neutrome/lilsdk", () => {
     );
   });
 
-  it("appends internal drafts with fixed SDK metadata and empty args", () => {
-    const request = parseChatCompletionsRequest(
-      encoder.encode(
-        JSON.stringify({
-          model: "virtual-model",
-          messages: [{ role: "user", content: "hello" }],
-        }),
-      ),
-    );
-
-    const updated = appendInternalDraft(request, "draft answer");
-    const emitted = JSON.parse(
-      decoder.decode(emitChatCompletionsRequest(updated)),
-    );
-
-    expect(emitted.messages[1].tool_calls[0].function.name).toBe(
-      INTERNAL_DRAFT_TOOL_NAME,
-    );
-    expect(emitted.messages[1].tool_calls[0].function.arguments).toBe("{}");
-    expect(emitted.messages[2].content).toBe("draft answer");
-  });
 
   it("appends generic synthetic tool interactions", () => {
     const request = parseChatCompletionsRequest(
@@ -241,279 +242,6 @@ describe("@neutrome/lilsdk", () => {
     });
   });
 
-  it("builds two-pass executors from model and settings resolvers", async () => {
-    const request = parseChatCompletionsRequest(
-      encoder.encode(
-        JSON.stringify({
-          model: "virtual-model",
-          messages: [{ role: "user", content: "hello" }],
-        }),
-      ),
-    );
-    const seen: Program[] = [];
-    const ctx = buildExecutorContext({
-      async invoke(_executor, program) {
-        seen.push(program);
-        if (seen.length === 1) {
-          return appendAssistantMessage(
-            { code: [], buffers: [] },
-            "draft answer",
-          );
-        }
-        return appendAssistantMessage(
-          { code: [], buffers: [] },
-          "final answer",
-        );
-      },
-      async *invokeStream() {
-        throw new Error("streaming path is not used in this test");
-      },
-    });
-
-    const executor = createTwoPassExecutor({
-      draft: "smart-model",
-      final: "base-model",
-      resolveFinalSettings: () => ({
-        reasoningLevel: "high",
-        systemPrompt: "system prompt",
-      }),
-    });
-
-    const result = await executor.execute(request, ctx);
-
-    expect(seen.map((program) => getModel(program))).toEqual([
-      "smart-model",
-      "base-model",
-    ]);
-    expect(contentText(result)).toBe("final answer");
-
-    const finalRequest = JSON.parse(
-      decoder.decode(emitChatCompletionsRequest(seen[1]!)),
-    );
-    expect(finalRequest.messages[0]).toEqual({
-      role: "system",
-      content: "system prompt",
-    });
-    expect(finalRequest.reasoning_effort).toBe("high");
-    expect(finalRequest.messages[2].tool_calls[0].function).toEqual({
-      name: INTERNAL_DRAFT_TOOL_NAME,
-      arguments: "{}",
-    });
-    expect(finalRequest.messages[3]).toEqual({
-      role: "tool",
-      tool_call_id: "knowledge_0",
-      content: "draft answer",
-    });
-  });
-
-  it("replaces draft system prompt and moves existing system prompt to first user message", async () => {
-    const request = parseChatCompletionsRequest(
-      encoder.encode(
-        JSON.stringify({
-          model: "virtual-model",
-          messages: [
-            { role: "system", content: "original system" },
-            { role: "user", content: "hello" },
-          ],
-        }),
-      ),
-    );
-    const seen: Program[] = [];
-    const ctx = buildExecutorContext({
-      async invoke(_executor, program) {
-        seen.push(program);
-        return appendAssistantMessage(
-          { code: [], buffers: [] },
-          seen.length === 1 ? "draft" : "final",
-        );
-      },
-      async *invokeStream() {
-        throw new Error("streaming path is not used in this test");
-      },
-    });
-
-    const executor = createTwoPassExecutor({
-      draft: "smart-model",
-      final: "base-model",
-      resolveDraftSettings: () => ({ systemPrompt: "draft system" }),
-    });
-
-    await executor.execute(request, ctx);
-
-    const draftRequest = JSON.parse(
-      decoder.decode(emitChatCompletionsRequest(seen[0]!)),
-    );
-    expect(draftRequest.messages).toEqual([
-      { role: "system", content: "draft system" },
-      { role: "user", content: "original system" },
-      { role: "user", content: "hello" },
-    ]);
-  });
-
-  it("composes model strings and custom executors", async () => {
-    const calls: Array<{ model: string; streaming: boolean }> = [];
-    const ctx = buildExecutorContext({
-      async invoke(_executor, program) {
-        calls.push({ model: getModel(program) ?? "", streaming: false });
-        return appendAssistantMessage(
-          { code: [], buffers: [] },
-          "model answer",
-        );
-      },
-      async *invokeStream(_executor, program) {
-        calls.push({ model: getModel(program) ?? "", streaming: true });
-        yield parseChatCompletionsStreamChunk(
-          encoder.encode(
-            JSON.stringify({
-              id: "stream-response",
-              model: "base-model",
-              choices: [{ index: 0, delta: { content: "hello" } }],
-            }),
-          ),
-        );
-      },
-    });
-
-    const request = parseChatCompletionsRequest(
-      encoder.encode(
-        JSON.stringify({
-          model: "virtual-model",
-          messages: [{ role: "user", content: "hello" }],
-        }),
-      ),
-    );
-    const first = await ctx.invoke("smart-model", request);
-    const chunks: Program[] = [];
-    for await (const chunk of ctx.invokeStream("base-model", request)) {
-      chunks.push(chunk);
-    }
-
-    expect(calls).toEqual([
-      { model: "smart-model", streaming: false },
-      { model: "base-model", streaming: true },
-    ]);
-    expect(contentText(first)).toBe("model answer");
-    expect(
-      decoder.decode(emitChatCompletionsStreamChunk(chunks[0]!)),
-    ).toContain("hello");
-    expect(getModel(request)).toBe("virtual-model");
-
-    const customExecutor = executorFromExecute(async () =>
-      appendAssistantMessage({ code: [], buffers: [] }, "custom answer"),
-    );
-    const custom = await ctx.invoke(customExecutor, request);
-    expect(contentText(custom)).toBe("custom answer");
-
-    const twoPass = createTwoPassExecutor({
-      draft: customExecutor,
-      final: customExecutor,
-    });
-    expect(contentText(await twoPass.execute(request, ctx))).toBe(
-      "custom answer",
-    );
-  });
-
-  it("can skip the draft pass and limits the final context length", async () => {
-    const request = parseChatCompletionsRequest(
-      encoder.encode(
-        JSON.stringify({
-          model: "virtual-model",
-          messages: [{ role: "user", content: "request" }],
-        }),
-      ),
-    );
-    const seen: Program[] = [];
-    const ctx = buildExecutorContext({
-      async invoke(_executor, program) {
-        seen.push(program);
-        return appendAssistantMessage(
-          { code: [], buffers: [] },
-          seen.length === 1 ? "a very long draft" : "final",
-        );
-      },
-      async *invokeStream() {
-        throw new Error("streaming path is not used in this test");
-      },
-    });
-
-    const executor = createTwoPassExecutor({
-      draft: "smart-model",
-      final: "base-model",
-      maxTotalContextLength: 10,
-      resolveDraftSettings: () => ({ systemPrompt: "draft" }),
-    });
-    await executor.execute(request, ctx);
-
-    const finalRequest = JSON.parse(
-      decoder.decode(emitChatCompletionsRequest(seen[1]!)),
-    );
-    expect(finalRequest.messages.at(-1)?.content).toBe("a v");
-
-    let receivedRequest: Program | undefined;
-    let receivedContext: ExecutorContext | undefined;
-    const directFinal = createTwoPassExecutor({
-      draft: "unused",
-      final: "base-model",
-      resolveDraftSettings: (incomingRequest, incomingContext) => {
-        receivedRequest = incomingRequest;
-        receivedContext = incomingContext;
-        return null;
-      },
-    });
-    await directFinal.execute(request, ctx);
-    expect(getModel(seen.at(-1)!)).toBe("base-model");
-    expect(receivedRequest).toBe(request);
-    expect(receivedContext).toBe(ctx);
-
-    const draftOnly = createTwoPassExecutor({
-      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[] = [];

package/test/tools.test.ts

@@ -5,8 +5,9 @@ import {
   Opcode,
   type Instruction,
   type Program,
+  viewProgram,
 } from "@neutrome/lil-engine";
-import { connectTools, ToolArgumentsError } from "../src/tools.ts";
+import { connectTools } from "../src/tools.ts";
 import type { ExecutorContext, Tool } from "../src/types.ts";
 
 function buildToolCallResponse(
@@ -173,22 +174,67 @@ describe("connectTools", () => {
     expect(hasAnswer).toBe(true);
   });
 
-  it("rejects malformed connected-tool arguments", async () => {
+  it("returns malformed connected-tool arguments to the model", async () => {
     const executor = connectTools([calculatorTool], "test-model");
+    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(
+      viewProgram(retryRequest!).messages.at(-1)?.toolResult?.text,
+    ).toBe('Tool "calculator" failed: Tool "calculator" received invalid JSON object arguments');
+    expect(callData(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 = connectTools([failingTool], "test-model");
+    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(
+      viewProgram(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 () => {