@neutrome/lilsdk 0.3.5 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neutrome/lilsdk",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -13,7 +13,7 @@
     "./managed": "./src/managed/index.ts"
   },
   "dependencies": {
-    "@neutrome/lil-engine": "0.3.4"
+    "@neutrome/lil-engine": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",

package/src/index.ts

@@ -1,8 +1,9 @@
 export type {
-  ExecutionTarget,
+  Cache,
+  CachePutOptions,
   Executor,
+  ExecutorInput,
   ExecutorContext,
-  InvokeOptions,
   OutputSink,
   ProgramTransform,
   ExecutionEvent,

package/src/loops/index.ts

@@ -1,5 +1,6 @@
 import { createProgram, deltaText, type Program } from "@neutrome/lil-engine";
-import type { Executor, ExecutorContext } from "../types.ts";
+import type { Executor, ExecutorContext, ExecutorInput } from "../types.ts";
+import { completeStream, streamStage } from "../stream/stages.ts";
 import { appendAssistantMessage } from "../synthetic/index.ts";
 
 export type RetryOptions = {
@@ -17,8 +18,8 @@ export type FallbackOptions = {
 };
 
 export type GoalExecutorOptions = {
-  draft: Executor;
-  review: Executor;
+  draft: ExecutorInput;
+  review: ExecutorInput;
   refine: (
     request: Program,
     answer: Program,
@@ -30,7 +31,7 @@ export type GoalExecutorOptions = {
 };
 
 export function retry(
-  executor: Executor,
+  executor: ExecutorInput,
   options: RetryOptions = {},
 ): Executor {
   const attempts = positiveInteger(options.attempts ?? 2, "retry attempts");
@@ -38,7 +39,7 @@ export function retry(
   return {
     execute(request, ctx) {
       return runRetry(
-        (attempt) => executor.execute(request, childContext(ctx, attempt)),
+        (attempt) => childContext(ctx, attempt).invoke(executor, request),
         attempts,
         options,
       );
@@ -50,9 +51,9 @@ export function retry(
       for (let attempt = 1; attempt <= attempts; attempt += 1) {
         let emitted = false;
         try {
-          for await (const chunk of executor.stream(
+          for await (const chunk of childContext(ctx, attempt).invokeStream(
+            executor,
             request,
-            childContext(ctx, attempt),
           )) {
             emitted = true;
             yield chunk;
@@ -77,7 +78,7 @@ export function retry(
 }
 
 export function fallback(
-  executors: readonly Executor[],
+  executors: readonly ExecutorInput[],
   options: FallbackOptions = {},
 ): Executor {
   if (executors.length === 0) {
@@ -88,7 +89,7 @@ export function fallback(
     execute(request, ctx) {
       return runFallback(
         (executor, index) =>
-          executor.execute(request, childContext(ctx, index + 1)),
+          childContext(ctx, index + 1).invoke(executor, request),
         executors,
         options,
       );
@@ -100,9 +101,9 @@ export function fallback(
       for (const [index, executor] of executors.entries()) {
         let emitted = false;
         try {
-          for await (const chunk of executor.stream(
+          for await (const chunk of childContext(ctx, index + 1).invokeStream(
+            executor,
             request,
-            childContext(ctx, index + 1),
           )) {
             emitted = true;
             yield chunk;
@@ -139,8 +140,8 @@ export function createGoalExecutor(options: GoalExecutorOptions): Executor {
 
       for (let attempt = 1; attempt <= maxIterations; attempt += 1) {
         const attemptContext = childContext(ctx, attempt);
-        answer = await options.draft.execute(current, attemptContext);
-        const review = await options.review.execute(answer, attemptContext);
+        answer = await attemptContext.invoke(options.draft, current);
+        const review = await attemptContext.invoke(options.review, answer);
         if (await options.satisfied(review, attempt)) return answer;
         if (attempt < maxIterations) {
           current = await options.refine(current, answer, review, attempt);
@@ -157,19 +158,24 @@ export function createGoalExecutor(options: GoalExecutorOptions): Executor {
       for (let attempt = 1; attempt <= maxIterations; attempt += 1) {
         const attemptContext = childContext(ctx, attempt);
         answer = yield* streamGoalStage(
-          options.draft.stream(current, attemptContext),
+          streamStage(attemptContext.invokeStream(options.draft, current)),
           current,
         );
         const review = yield* streamGoalStage(
-          options.review.stream(answer, attemptContext),
+          streamStage(attemptContext.invokeStream(options.review, answer)),
           answer,
         );
 
-        if (await options.satisfied(review, attempt)) return;
+        if (await options.satisfied(review, attempt)) {
+          yield completeStream();
+          return;
+        }
         if (attempt < maxIterations) {
           current = await options.refine(current, answer, review, attempt);
         }
       }
+
+      yield completeStream();
     },
   };
 }
@@ -218,8 +224,8 @@ async function runRetry<T>(
 }
 
 async function runFallback<T>(
-  operation: (executor: Executor, index: number) => Promise<T>,
-  executors: readonly Executor[],
+  operation: (executor: ExecutorInput, index: number) => Promise<T>,
+  executors: readonly ExecutorInput[],
   options: FallbackOptions,
 ): Promise<T> {
   let lastError: unknown;

package/src/managed/capabilities.ts

@@ -0,0 +1,215 @@
+import {
+  addTool,
+  clearIndices,
+  toolDefinitions,
+  viewProgram,
+  type Program,
+  type ProgramTool,
+} from "@neutrome/lil-engine";
+import { connectTools } from "../tools.ts";
+import type {
+  Executor,
+  ExecutorContext,
+  ExecutorInput,
+  Tool,
+} from "../types.ts";
+
+const capabilityToolName = "learn_capability";
+const encoder = new TextEncoder();
+
+export type CapabilitiesExecutorOptions = {
+  enabledIterations?: number;
+  cacheKey?: (ctx: ExecutorContext) => string;
+};
+
+type CapabilitySelection = { toolName: string; remaining: number };
+
+export function createCapabilitiesExecutor(
+  inner: ExecutorInput,
+  options: CapabilitiesExecutorOptions = {},
+): Executor {
+  const enabledIterations = positiveInteger(options.enabledIterations ?? 5);
+  const cacheKey = options.cacheKey ?? ((ctx) => ctx.requestId);
+
+  return {
+    async execute(request, ctx) {
+      const tools = viewProgram(request).tools;
+      if (tools.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),
+        ctx,
+      );
+    },
+
+    async *stream(request, ctx) {
+      const tools = viewProgram(request).tools;
+      if (tools.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),
+        ctx,
+      );
+    },
+  };
+}
+
+function connectCapabilities(
+  inner: ExecutorInput,
+  tools: readonly ProgramTool[],
+  key: string,
+  enabledIterations: number,
+): Executor {
+  const selectedInner: Executor = {
+    async execute(request, ctx) {
+      return ctx.invoke(
+        inner,
+        await withSelectedTool(request, ctx, key, tools),
+      );
+    },
+    async *stream(request, ctx) {
+      yield* ctx.invokeStream(
+        inner,
+        await withSelectedTool(request, ctx, key, tools),
+      );
+    },
+  };
+
+  return connectTools(
+    [learnCapabilityTool(tools, key, enabledIterations)],
+    selectedInner,
+  );
+}
+
+function learnCapabilityTool(
+  tools: readonly ProgramTool[],
+  key: string,
+  enabledIterations: number,
+): Tool {
+  return {
+    name: capabilityToolName,
+    description: `Enable one capability for the next ${enabledIterations} upstream iterations. Available capabilities: ${tools.map((tool) => tool.name).join(", ")}.`,
+    schema: {
+      type: "object",
+      properties: { capability: { type: "string" } },
+      required: ["capability"],
+      additionalProperties: false,
+    },
+    async execute(args, ctx) {
+      const name = typeof args.capability === "string" ? args.capability : "";
+      if (!tools.some((tool) => tool.name === name)) {
+        return `Unknown capability: ${name || "(missing)"}.`;
+      }
+      await writeSelection(ctx, key, {
+        toolName: name,
+        remaining: enabledIterations,
+      });
+      return `Enabled ${name} for the next ${enabledIterations} upstream iterations.`;
+    },
+  };
+}
+
+async function withSelectedTool(
+  request: Program,
+  ctx: ExecutorContext,
+  key: string,
+  tools: readonly ProgramTool[],
+): Promise<Program> {
+  const selection = await readSelection(ctx, key);
+  if (!selection || selection.remaining < 1) return request;
+
+  const tool = tools.find((candidate) => candidate.name === selection.toolName);
+  if (!tool) {
+    await ctx.cache.delete(key);
+    return request;
+  }
+
+  if (selection.remaining === 1) {
+    await ctx.cache.delete(key);
+  } else {
+    await writeSelection(ctx, key, {
+      ...selection,
+      remaining: selection.remaining - 1,
+    });
+  }
+  return addProgramTool(request, tool);
+}
+
+async function discardMissingSelection(
+  ctx: ExecutorContext,
+  key: string,
+  tools: readonly ProgramTool[],
+): Promise<void> {
+  const selection = await readSelection(ctx, key);
+  if (selection && !tools.some((tool) => tool.name === selection.toolName)) {
+    await ctx.cache.delete(key);
+  }
+}
+
+function withoutTools(request: Program): Program {
+  const indices: number[] = [];
+  for (const definition of toolDefinitions(request)) {
+    for (let index = definition.start; index <= definition.end; index += 1) {
+      indices.push(index);
+    }
+  }
+  return clearIndices(request, indices);
+}
+
+function addProgramTool(request: Program, tool: ProgramTool): Program {
+  return addTool(
+    request,
+    tool.name,
+    tool.description,
+    encoder.encode(JSON.stringify(tool.schema)),
+  );
+}
+
+async function readSelection(
+  ctx: ExecutorContext,
+  key: string,
+): Promise<CapabilitySelection | null> {
+  const value = await ctx.cache.get(key);
+  if (!value) return null;
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      typeof (parsed as CapabilitySelection).toolName === "string" &&
+      Number.isInteger((parsed as CapabilitySelection).remaining)
+    ) {
+      return parsed as CapabilitySelection;
+    }
+  } catch {
+    // Treat malformed cache data as an expired selection.
+  }
+  await ctx.cache.delete(key);
+  return null;
+}
+
+function writeSelection(
+  ctx: ExecutorContext,
+  key: string,
+  selection: CapabilitySelection,
+): Promise<void> {
+  return ctx.cache.put(key, JSON.stringify(selection));
+}
+
+function selectionKey(key: string): string {
+  return `capabilities:${key}`;
+}
+
+function positiveInteger(value: number): number {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error("enabledIterations must be a positive integer");
+  }
+  return value;
+}

package/src/managed/index.ts

@@ -1,18 +1,16 @@
-export { createTargetExecutor } from "./target-executor.ts";
+export { createCapabilitiesExecutor } from "./capabilities.ts";
+export type { CapabilitiesExecutorOptions } from "./capabilities.ts";
 
 export {
   appendInternalDraft,
   createTwoPassExecutor,
   INTERNAL_DRAFT_CALL_ID,
   INTERNAL_DRAFT_TOOL_NAME,
-  invokeExecutor,
-  streamExecutor,
-} from "./twoPassExecutor.ts";
+} from "./two-pass.ts";
 
 export type {
   InternalDraft,
-  ModelExecutor,
   TwoPassExecutorOptions,
   TwoPassSettings,
   TwoPassSettingsResolver,
-} from "./twoPassExecutor.ts";
+} from "./two-pass.ts";

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),
       );
     },
   };