@xandreed/plugin-agent-loop 0.3.0 → 0.4.0

package/README.md

@@ -1,5 +1,5 @@
 # @xandreed/plugin-agent-loop
 
-Efferent composable agent framework, 0.3.0. Bun on Linux.
+Efferent composable agent framework, 0.4.0. Bun on Linux.
 
 Documentation: https://github.com/xandreeddev/efferent

package/dist/loop.d.ts

@@ -1,4 +1,4 @@
-import { LanguageModel, Prompt } from "@effect/ai";
+import { AiError, LanguageModel, Prompt } from "@effect/ai";
 import type { Tool, Toolkit } from "@effect/ai";
 import { Effect, Option } from "effect";
 import type { LoopEvent } from "@xandreed/core";
@@ -26,6 +26,23 @@ export interface CompactionPlan {
  * `Effect.iterate` — the same discipline as foundry's forge loop.
  */
 export interface RunLoopOptions<Tools extends Record<string, Tool.Any>, R> {
+    /** A host-validated first batch. Runs as step zero through the ordinary
+     * Effect AI decoder, instrumented toolkit and durable tail hooks, without
+     * another provider request. Provider usage belongs to the host planner. */
+    readonly initialStep?: ReadonlyArray<{
+        readonly name: keyof Tools & string;
+        readonly params: unknown;
+    }>;
+    /** Host selection at a real provider boundary. Never called for initialStep.
+     * The host may cache its choice for a run; tools and completion remain loop-owned. */
+    readonly prepareModel?: (input: {
+        readonly stepIndex: number;
+        readonly messages: ReadonlyArray<AgentMessage>;
+        readonly activeTools: ReadonlyArray<string>;
+    }) => Effect.Effect<{
+        readonly model: LanguageModel.Service;
+        readonly system: Prompt.Prompt;
+    }, AiError.AiError, R>;
     readonly system: string | Prompt.Prompt;
     /** Explicit opt-in: export prompt and result content on step spans.
      * Hosts own consent, redaction and exporter retention. Disabled by default. */
@@ -190,4 +207,4 @@ export declare const runLoop: <Tools extends Record<string, Tool.Any>, R = never
     })[];
     outcome: "ok" | "partial";
     reason: "completed" | "step-cap" | "degenerate-loop";
-}, import("@effect/ai/AiError").AiError, LanguageModel.LanguageModel | Exclude<R, import("effect/Tracer").ParentSpan> | Exclude<Tool.HandlersFor<Tools>, import("effect/Tracer").ParentSpan>>;
+}, AiError.AiError, LanguageModel.LanguageModel | Exclude<R, import("effect/Tracer").ParentSpan> | Exclude<Tool.HandlersFor<Tools>, import("effect/Tracer").ParentSpan>>;

package/dist/loop.js

@@ -1,4 +1,4 @@
-import { LanguageModel, Prompt } from "@effect/ai";
+import { AiError, LanguageModel, Prompt } from "@effect/ai";
 import { Cause, Effect, Exit, Match, Metric, Option, Ref, Stream } from "effect";
 import { foldStreamParts } from "@xandreed/core";
 import { CurrentAgentStep } from "@xandreed/core";
@@ -42,7 +42,7 @@ export const foldProgress = (state, sig) => {
     yield* onEvent({ type: "turn_start", turnIndex: state.turnIndex });
     const active = options.activeTools === void 0 ? Object.keys(toolkit.tools) : yield* options.activeTools().pipe(Effect.provide(eventContext)), selectedTools = Object.fromEntries(Object.entries(toolkit.tools).filter(([name]) => active.includes(name))), toolNames = Object.keys(selectedTools);
     yield* Effect.annotateCurrentSpan({ "engine.tools.active": toolNames });
-    const instructions = typeof options.system === "string" ? Prompt.make([{ role: "system", content: options.system }]) : options.system, prompt = Prompt.merge(instructions, Prompt.make(toPromptMessages(state.messages)));
+    const prepared = state.turnIndex === 0 && options.initialStep !== void 0 ? Option.none() : options.prepareModel === void 0 ? Option.none() : Option.some(yield* options.prepareModel({ stepIndex: state.turnIndex, messages: state.messages, activeTools: toolNames }).pipe(Effect.provide(eventContext))), baseSystem = Option.match(prepared, { onNone: () => options.system, onSome: (value) => value.system }), instructions = typeof baseSystem === "string" ? Prompt.make([{ role: "system", content: baseSystem }]) : baseSystem, prompt = Prompt.merge(instructions, Prompt.make(toPromptMessages(state.messages)));
     if (options.captureTraceContent === !0)
       yield* Effect.annotateCurrentSpan({
         "engine.step.input": JSON.stringify({ messages: prompt.content, activeTools: toolNames })
@@ -66,14 +66,14 @@ export const foldProgress = (state, sig) => {
         })
       },
       concurrency: options.toolConcurrency ?? DEFAULT_TOOL_CONCURRENCY
-    }, settled = (streamingHealthy) => LanguageModel.generateText(callOptions).pipe(Effect.map((res) => ({
+    }, settled = (streamingHealthy) => (Option.isSome(prepared) ? prepared.value.model.generateText(callOptions) : LanguageModel.generateText(callOptions)).pipe(Effect.map((res) => ({
       _tag: "ok",
       content: res.content,
       finishReason: res.finishReason,
       usage: res.usage,
       streamingHealthy
     }))), streamed = Effect.gen(function* () {
-      const partSeen = yield* Ref.make(!1), folded = yield* foldStreamParts(LanguageModel.streamText(callOptions).pipe(Stream.tap(() => Ref.set(partSeen, !0))), (delta) => onEvent({
+      const partSeen = yield* Ref.make(!1), folded = yield* foldStreamParts((Option.isSome(prepared) ? prepared.value.model.streamText(callOptions) : LanguageModel.streamText(callOptions)).pipe(Stream.tap(() => Ref.set(partSeen, !0))), (delta) => onEvent({
         type: "assistant_delta",
         turnIndex: state.turnIndex,
         channel: delta.channel,
@@ -91,7 +91,20 @@ export const foldProgress = (state, sig) => {
         onSome: Effect.succeed,
         onNone: () => Effect.logWarning("streaming failed before any part arrived \u2014 falling back to generateText for this run").pipe(Effect.zipRight(settled(!1)))
       });
-    }), outcome = yield* (options.streaming === !0 && state.streamingHealthy ? streamed : settled(state.streamingHealthy)).pipe(Effect.catchAll((err) => err?._tag === "MalformedOutput" ? Effect.succeed({ _tag: "malformed", err }) : Effect.fail(err)), Effect.locally(CurrentEmptyResponseTolerance, state.toolCalls > 0));
+    }), planned = state.turnIndex === 0 && options.initialStep !== void 0, initial = Effect.gen(function* () {
+      const provider = yield* LanguageModel.make({
+        generateText: () => Effect.succeed([...(options.initialStep ?? []).map((call, index) => ({
+          type: "tool-call",
+          id: `planned:0:${index}`,
+          name: call.name,
+          params: call.params,
+          providerExecuted: !1
+        })), { type: "finish", reason: "tool-calls", usage: { inputTokens: void 0, outputTokens: void 0, totalTokens: void 0 } }]),
+        streamText: () => Stream.empty
+      });
+      yield* Effect.annotateCurrentSpan("engine.step.host_planned", !0);
+      return yield* settled(state.streamingHealthy).pipe(Effect.provideService(LanguageModel.LanguageModel, provider));
+    }), useStreaming = options.streaming === !0 && state.streamingHealthy, outcome = yield* (planned ? initial : useStreaming ? streamed : settled(state.streamingHealthy)).pipe(Effect.catchAll((err) => err?._tag === "MalformedOutput" ? Effect.succeed({ _tag: "malformed", err }) : Effect.fail(err)), Effect.locally(CurrentEmptyResponseTolerance, state.toolCalls > 0));
     if (outcome._tag === "malformed") {
       const streak = state.malformedStreak + 1;
       if (streak >= MAX_MALFORMED)
@@ -121,10 +134,11 @@ This usually means you called a tool that doesn't exist or used the wrong argume
     const content = withToolCallIds(outcome.content, state.turnIndex), usage = extractUsage(outcome.usage, content);
     yield* Effect.annotateCurrentSpan({
       "engine.step.finish_reason": outcome.finishReason,
-      "engine.step.usage": JSON.stringify(usage),
+      "engine.step.usage_available": !planned,
+      ...!planned ? { "engine.step.usage": JSON.stringify(usage) } : {},
       ...options.captureTraceContent === !0 ? { "engine.step.output": JSON.stringify({ content, usage, finishReason: outcome.finishReason }) } : {}
     });
-    const model = extractModel(content), tail = withUsageOnAssistant(responseToAgentMessages(content), usage, model), positions = yield* options.onTail?.(tail) ?? Effect.succeed([]), assistantAt = tail.findIndex((m) => m.role === "assistant"), assistantPosition = assistantAt >= 0 ? Option.fromNullable(positions[assistantAt]) : Option.none(), text = responseText(content), toolCalls = responseToolCalls(content);
+    const model = extractModel(content), tail = planned ? responseToAgentMessages(content) : withUsageOnAssistant(responseToAgentMessages(content), usage, model), positions = yield* options.onTail?.(tail) ?? Effect.succeed([]), assistantAt = tail.findIndex((m) => m.role === "assistant"), assistantPosition = assistantAt >= 0 ? Option.fromNullable(positions[assistantAt]) : Option.none(), text = responseText(content), toolCalls = responseToolCalls(content);
     yield* onEvent({
       type: "assistant_message",
       turnIndex: state.turnIndex,

package/dist/plugin.adapter.js

@@ -5,7 +5,7 @@ import { runLoop } from "./loop.js";
 const Config = Schema.Struct({ maxSteps: Schema.Int.pipe(Schema.between(1, 1000)), toolConcurrency: Schema.Int.pipe(Schema.between(1, 32)), streaming: Schema.Boolean });
 export const agentLoopPlugin = definePlugin({
   id: "@xandreed/plugin-agent-loop",
-  version: "0.3.0",
+  version: "0.4.0",
   config: Config,
   defaults: { maxSteps: 100, toolConcurrency: 1, streaming: !0 },
   requires: [LanguageModel.LanguageModel, AgentTools, SessionStore, Memory, ContextManager],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xandreed/plugin-agent-loop",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -10,7 +10,7 @@
     }
   },
   "dependencies": {
-    "@xandreed/core": "0.3.0",
+    "@xandreed/core": "0.4.0",
     "@effect/ai": "0.35.0",
     "effect": "3.21.4"
   },