@neutrome/lilsdk 0.3.5 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neutrome/lilsdk",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "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.1"
   },
   "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/attachment-to-text.ts

@@ -0,0 +1,175 @@
+import {
+  contentText,
+  insertAfter,
+  isAttachmentOpcode,
+  messages,
+  programAttachments,
+  type Program,
+  type ProgramAttachment,
+} from "@neutrome/lil-engine";
+import {
+  appendToolInteraction,
+  prependSystemPrompt,
+} from "../synthetic/index.ts";
+import type { Executor, ExecutorContext, ExecutorInput } from "../types.ts";
+
+const toolName = "attachment_to_text";
+const defaultPrompt =
+  "Read the attached file carefully. Return a detailed factual description of its content for another assistant to use. Include all relevant visible text, structure, and details. Do not discuss this instruction.";
+
+export type AttachmentReaderRule = {
+  mimeTypes: readonly string[];
+  executor: ExecutorInput;
+};
+
+export type AttachmentToTextOptions = {
+  systemPrompt?: string;
+  cacheKey?: (attachment: ProgramAttachment, ctx: ExecutorContext) => string;
+};
+
+export function createAttachmentToTextExecutor(
+  inner: ExecutorInput,
+  rules: readonly AttachmentReaderRule[],
+  options: AttachmentToTextOptions = {},
+): Executor {
+  if (rules.length === 0)
+    throw new Error("attachment-to-text requires at least one reader rule");
+
+  const prompt = options.systemPrompt ?? defaultPrompt;
+  return {
+    async execute(request, ctx) {
+      return ctx.invoke(
+        inner,
+        await prepareRequest(request, ctx, rules, prompt, options),
+      );
+    },
+    async *stream(request, ctx) {
+      yield* ctx.invokeStream(
+        inner,
+        await prepareRequest(request, ctx, rules, prompt, options),
+      );
+    },
+  };
+}
+
+async function prepareRequest(
+  request: Program,
+  ctx: ExecutorContext,
+  rules: readonly AttachmentReaderRule[],
+  prompt: string,
+  options: AttachmentToTextOptions,
+): Promise<Program> {
+  const attachments = programAttachments(request);
+  if (attachments.length === 0) return request;
+  const latestUserStart = [...attachments]
+    .filter((attachment) => attachment.message.role === "user")
+    .at(-1)?.message.start;
+  let result = stripAttachments(request);
+  const sourceMessages = messages(request);
+
+  for (const attachment of [...attachments].reverse()) {
+    const rule = rules.find((candidate) =>
+      candidate.mimeTypes.some((mime) =>
+        matchesMime(mime, attachment.mimeType),
+      ),
+    );
+    if (!rule) {
+      if (attachment.message.start === latestUserStart) {
+        throw new Error(`No attachment reader matches ${attachment.mimeType}`);
+      }
+      throw new Error(
+        `Missing cached attachment description for historical ${attachment.mimeType}`,
+      );
+    }
+    const key = await attachmentCacheKey(attachment, ctx, options);
+    let description = await ctx.cache.get(key);
+    if (!description) {
+      if (attachment.message.start !== latestUserStart) {
+        throw new Error(
+          `Missing cached attachment description for historical ${attachment.mimeType}`,
+        );
+      }
+      const readerRequest = readerProgram(request, attachment, prompt);
+      description = contentText(await ctx.invoke(rule.executor, readerRequest));
+      if (!description.trim())
+        throw new Error(
+          `Attachment reader returned no text for ${attachment.mimeType}`,
+        );
+      await ctx.cache.put(key, description);
+    }
+    const interaction = {
+      callId: `attachment_${key.slice(-24)}`,
+      name: toolName,
+      args: {
+        mimeType: attachment.mimeType,
+        ...(attachment.name ? { name: attachment.name } : {}),
+        context:
+          "The user attached this file. Its binary media was replaced with the reconstructed text result below.",
+      },
+      result: `Reconstructed content for the file the user attached. The original binary media is not present in this context.\n\n${description}`,
+    };
+    const messageIndex = sourceMessages.findIndex(
+      (message) => message.start === attachment.message.start,
+    );
+    const targetMessage = messages(result)[messageIndex];
+    if (!targetMessage)
+      throw new Error("Attachment message was removed from context");
+    const synthetic = appendToolInteraction(
+      { code: [], buffers: [] },
+      interaction,
+    );
+    result = insertAfter(result, targetMessage.end, synthetic.code);
+  }
+  return result;
+}
+
+function readerProgram(
+  request: Program,
+  attachment: ProgramAttachment,
+  prompt: string,
+): Program {
+  return prependSystemPrompt(
+    {
+      code: request.code.slice(
+        attachment.message.start,
+        attachment.message.end + 1,
+      ),
+      buffers: request.buffers.map((buffer) => buffer.slice()),
+    },
+    prompt,
+  );
+}
+
+function stripAttachments(request: Program): Program {
+  return {
+    code: request.code.filter(
+      (instruction) => !isAttachmentOpcode(instruction.opcode),
+    ),
+    buffers: request.buffers.map((buffer) => buffer.slice()),
+  };
+}
+
+async function attachmentCacheKey(
+  attachment: ProgramAttachment,
+  ctx: ExecutorContext,
+  options: AttachmentToTextOptions,
+): Promise<string> {
+  if (options.cacheKey)
+    return `attachment-to-text:${options.cacheKey(attachment, ctx)}`;
+  const bytes = new TextEncoder().encode(
+    JSON.stringify({
+      mimeType: attachment.mimeType,
+      url: attachment.url,
+      name: attachment.name,
+    }),
+  );
+  const hash = await crypto.subtle.digest("SHA-256", bytes);
+  return `attachment-to-text:${Array.from(new Uint8Array(hash), (value) => value.toString(16).padStart(2, "0")).join("")}`;
+}
+
+function matchesMime(pattern: string, mimeType: string): boolean {
+  return (
+    pattern === mimeType ||
+    (pattern.endsWith("/*") && mimeType.startsWith(pattern.slice(0, -1)))
+  );
+}

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,21 @@
-export { createTargetExecutor } from "./target-executor.ts";
+export { createCapabilitiesExecutor } from "./capabilities.ts";
+export type { CapabilitiesExecutorOptions } from "./capabilities.ts";
+export { createAttachmentToTextExecutor } from "./attachment-to-text.ts";
+export type {
+  AttachmentReaderRule,
+  AttachmentToTextOptions,
+} from "./attachment-to-text.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";