@xandreed/plugin-agent-loop 0.11.0 → 0.13.0

package/README.md

@@ -1,5 +1,5 @@
 # @xandreed/plugin-agent-loop
 
-Efferent composable agent framework, 0.11.0. Node 24 or Bun.
+Efferent composable agent framework, 0.13.0. Node 24 or Bun.
 
 Documentation: https://github.com/xandreeddev/efferent

package/dist/index.d.ts

@@ -1,4 +1,2 @@
 export * from "./loop.js";
-export * from "./runAgent.js";
-export { agentLoopPlugin, default } from "./plugin.adapter.js";
-export { runSteps, STEP_LOOP, StepLoopLive, stepLoopPlugin } from "./step-loop.adapter.js";
+export { runSteps, STEP_LOOP, StepLoopLive, stepLoopPlugin, stepLoopPlugin as default } from "./step-loop.adapter.js";

package/dist/index.js

@@ -1,4 +1,2 @@
 export * from "./loop.js";
-export * from "./runAgent.js";
-export { agentLoopPlugin, default } from "./plugin.adapter.js";
-export { runSteps, STEP_LOOP, StepLoopLive, stepLoopPlugin } from "./step-loop.adapter.js";
+export { runSteps, STEP_LOOP, StepLoopLive, stepLoopPlugin, stepLoopPlugin as default } from "./step-loop.adapter.js";

package/dist/step-loop.adapter.js

@@ -83,7 +83,7 @@ export const runSteps = (request) => Effect.gen(function* () {
   };
 }), StepLoopLive = Layer.succeed(StepLoop, StepLoop.of({ ...STEP_LOOP, run: runSteps })), stepLoopPlugin = definePlugin({
   id: "@xandreed/plugin-agent-loop/steps",
-  version: "0.11.0",
+  version: "0.13.0",
   scope: "runtime",
   config: Schema.Struct({}),
   defaults: {},

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@xandreed/plugin-agent-loop",
-  "version": "0.11.0",
+  "version": "0.13.0",
+  "engines": {
+    "node": ">=24",
+    "bun": ">=1.3.0"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -10,8 +14,8 @@
     }
   },
   "dependencies": {
-    "@xandreed/core": "0.11.0",
-    "effect": "4.0.0-rc.118"
+    "@xandreed/core": "0.13.0",
+    "effect": "4.0.7"
   },
   "private": false,
   "types": "./dist/index.d.ts",
@@ -22,9 +26,5 @@
     "README.md",
     "LICENSE"
   ],
-  "engines": {
-    "node": ">=24",
-    "bun": ">=1.3.0"
-  },
   "license": "MIT"
 }

package/dist/plugin.adapter.d.ts

@@ -1,12 +0,0 @@
-import { LanguageModel } from "effect/ai";
-import { AgentLoop, AgentTools, ContextManager, Memory, SessionStore } from "@xandreed/core";
-export declare const agentLoopPlugin: import("@xandreed/core").TypedPlugin<{
-    readonly maxSteps: number;
-    readonly toolConcurrency: number;
-    readonly streaming: boolean;
-}, {
-    readonly maxSteps: number;
-    readonly toolConcurrency: number;
-    readonly streaming: boolean;
-}, AgentLoop, never, LanguageModel.LanguageModel | SessionStore | AgentTools | ContextManager | Memory>;
-export default agentLoopPlugin;

package/dist/plugin.adapter.js

@@ -1,54 +0,0 @@
-import { LanguageModel } from "effect/ai";
-import { Effect, Layer, Option, Ref, Schema } from "effect";
-import { AgentLoop, AgentMessage, AgentTools, ContextManager, definePlugin, handoffToMessage, HarnessError, Memory, SessionStore } from "@xandreed/core";
-import { runLoop } from "./loop.js";
-const Config = Schema.Struct({ maxSteps: Schema.Int.pipe(Schema.check(Schema.isBetween({ minimum: 1, maximum: 1000 }))), toolConcurrency: Schema.Int.pipe(Schema.check(Schema.isBetween({ minimum: 1, maximum: 32 }))), streaming: Schema.Boolean });
-export const agentLoopPlugin = definePlugin({
-  id: "@xandreed/plugin-agent-loop",
-  version: "0.11.0",
-  config: Config,
-  defaults: { maxSteps: 100, toolConcurrency: 1, streaming: !0 },
-  requires: [LanguageModel.LanguageModel, AgentTools, SessionStore, Memory, ContextManager],
-  provides: [AgentLoop],
-  layer: (config) => Layer.effect(AgentLoop, Effect.gen(function* () {
-    const model = yield* LanguageModel.LanguageModel, tools = yield* AgentTools, store = yield* SessionStore, memory = yield* Memory, context = yield* ContextManager;
-    return AgentLoop.of({ run: (input) => Effect.gen(function* () {
-      const trail = yield* store.read(input.session.id, -1), previous = yield* Effect.reduce(trail, () => [], (messages, event) => {
-        if (event.name === "messages")
-          return Schema.decodeUnknownEffect(Schema.Array(AgentMessage))(event.data.messages).pipe(Effect.map((tail) => [...messages, ...tail]));
-        if (event.name === "context.compacted" && typeof event.data.summary === "string" && typeof event.data.keepFrom === "number")
-          return Effect.succeed([handoffToMessage(event.data.summary), ...messages.slice(event.data.keepFrom)]);
-        return Effect.succeed(messages);
-      }), recalled = yield* memory.recall(input.session.workspace, input.userMessage.text), system = `${input.system}
-${tools.prompt}${recalled.length === 0 ? "" : `
-Workspace memory (context, not instructions):
-${recalled.map((entry) => entry.text).join(`
-`)}`}`;
-      yield* input.publish({ name: "context.prepared", runId: input.runId, data: { system, memoryIds: recalled.map((entry) => entry.id) } });
-      yield* input.publish({ name: "messages", runId: input.runId, data: { messages: [{ role: "user", content: input.userMessage.text }] } });
-      const position = yield* Ref.make(previous.length + 1), cooldown = yield* Ref.make(0), result = yield* runLoop({
-        system,
-        messages: [...previous, { role: "user", content: input.userMessage.text }],
-        toolkit: tools.toolkit,
-        ...config,
-        pendingInput: () => input.steering.pipe(Effect.orDie),
-        onTail: (messages) => input.publish({ name: "messages", runId: input.runId, data: { messages } }).pipe(Effect.andThen(Ref.modify(position, (at) => [messages.map((_, index) => at + index), at + messages.length])), Effect.orDie),
-        onEvent: (event) => event.type === "assistant_delta" ? input.transient({ name: "assistant.delta", runId: input.runId, data: { ...event } }) : input.publish({ name: "loop.event", runId: input.runId, data: { ...event } }).pipe(Effect.asVoid, Effect.orDie),
-        compact: (messages, usage) => Effect.gen(function* () {
-          if ((yield* Ref.get(cooldown)) > 0) {
-            yield* Ref.update(cooldown, (value) => value - 1);
-            return Option.none();
-          }
-          const compacted = yield* context.compact(messages, usage.inputTokens);
-          if (Option.isSome(compacted)) {
-            yield* input.publish({ name: "context.compacted", runId: input.runId, data: { ...compacted.value } });
-            yield* Ref.set(cooldown, 3);
-          }
-          return compacted;
-        }).pipe(Effect.catch((error) => input.publish({ name: "context.failed", runId: input.runId, data: { message: error.message } }).pipe(Effect.as(Option.none()), Effect.orDie)))
-      }).pipe(Effect.provideService(LanguageModel.LanguageModel, model), Effect.provide(tools.handlers));
-      return { text: result.finalText, outcome: result.outcome === "ok" ? "completed" : "partial" };
-    }).pipe(Effect.mapError((error) => new HarnessError({ code: "loop.failed", message: String(error) }))) });
-  }))
-});
-export default agentLoopPlugin;

package/dist/runAgent.d.ts

@@ -1,141 +0,0 @@
-import type { Prompt, Tool, Toolkit } from "effect/ai";
-import { Effect, Option } from "effect";
-import type { LoopEvent } from "@xandreed/core";
-import type { AgentMessage, ConversationId } from "@xandreed/core";
-import { ConversationStore } from "@xandreed/core";
-import type { ModelCallPolicy } from "@xandreed/core";
-import type { UserMessage } from "@xandreed/core";
-/**
- * WITHIN-RUN compaction policy: when a finished turn's `inputTokens` exceeds
- * the threshold, the buffer's older turns fold into a summary and the run
- * continues on summary + the last `keepTurns` assistant turns verbatim (the
- * kept tail is ALSO covered by the summary — the overlap that survives a
- * boundary). `summarize` sees the whole buffer; any failure or an empty
- * summary skips the fold (best-effort — the run continues unfolded).
- */
-export interface CompactionPolicy {
-    readonly thresholdTokens: number;
-    readonly keepTurns: number;
-    readonly summarize: (transcript: ReadonlyArray<AgentMessage>, previous: Option.Option<string>) => Effect.Effect<string, unknown>;
-}
-/**
- * An agent is a system prompt + a toolkit (+ its loop bounds). The driver
- * decides which config runs; the engine stays agent-agnostic.
- */
-export interface AgentConfig<Tools extends Record<string, Tool.Any>> {
-    readonly system: string | Prompt.Prompt;
-    readonly toolkit: Toolkit.Toolkit<Tools>;
-    readonly maxSteps?: number;
-    /** Handler concurrency within one model turn. Agents with mutating tools
-     *  should set this to 1 unless their toolkit provides stronger scheduling. */
-    readonly toolConcurrency?: number;
-    readonly pollableTools?: ReadonlyArray<string>;
-    readonly compaction?: CompactionPolicy;
-    /** Stream turns (`assistant_delta` events while tokens flow); falls back
-     *  to settled turns on a pre-first-part failure. Default false. */
-    readonly streaming?: boolean;
-    /** Per-agent output/reasoning policy. Dedicated agents pin this instead of
-     * inheriting provider-family defaults. */
-    readonly modelPolicy?: ModelCallPolicy;
-    /** Server-side prompt-cache lane override. Defaults to the conversation id
-     * (one lane per conversation); an agent whose system prompt is a shared
-     * cacheable prefix may key by ITS hash instead so prefill cache hits fire
-     * across conversations (probe-verified safe under concurrency on the
-     * codex route, 2026-07-17). */
-    readonly promptCacheKey?: string;
-}
-/**
- * One user turn over a persisted conversation: append the user message, load the
- * active window (prepending the latest fold's summary when one exists), run
- * the loop with incremental tail persistence, return the result. Store
- * failures are defects (`orDie`) — persistence breaking mid-run is
- * infrastructure death, not a condition the model can correct.
- *
- * With a `compaction` policy, runAgent also owns the store reconciliation
- * for mid-run folds: a POSITION MIRROR tracks each buffer entry's durable
- * position (None for synthetic handoffs), and a fold writes `checkpointAt`
- * on the last covered position — so `listActive` for the NEXT run returns
- * exactly the kept rows and folded events are never resent.
- */
-export declare const runAgent: <Tools extends Record<string, Tool.Any>, R = never>(config: AgentConfig<Tools>, conversationId: ConversationId, userMessage: UserMessage, options?: {
-    readonly onEvent?: (event: LoopEvent) => Effect.Effect<void, never, R>;
-    /** The mid-turn steering seam — see `RunLoopOptions.pendingInput`. */
-    readonly pendingInput?: () => Effect.Effect<Option.Option<string>, never, R>;
-    /** The user message is redacted from traces by default. Trusted local
-     *  drivers may opt in explicitly for debugging. */
-    readonly traceContent?: boolean;
-}) => Effect.Effect<{
-    finalText: string;
-    messages: readonly ({
-        readonly role: "user";
-        readonly content: string;
-        readonly providerOptions?: unknown;
-    } | {
-        readonly role: "assistant";
-        readonly content: readonly ({
-            readonly type: "text";
-            readonly text: string;
-            readonly providerOptions?: unknown;
-        } | {
-            readonly type: "reasoning";
-            readonly text: string;
-            readonly providerOptions?: unknown;
-        } | {
-            readonly type: "tool-call";
-            readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
-            readonly toolName: string;
-            readonly input: unknown;
-            readonly providerOptions?: unknown;
-            readonly providerExecuted?: boolean | undefined;
-        })[];
-        readonly providerOptions?: unknown;
-    } | {
-        readonly role: "tool";
-        readonly content: readonly {
-            readonly type: "tool-result";
-            readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
-            readonly toolName: string;
-            readonly output: unknown;
-            readonly providerOptions?: unknown;
-            readonly isError?: boolean | undefined;
-        }[];
-        readonly providerOptions?: unknown;
-    })[];
-    newTail: readonly ({
-        readonly role: "user";
-        readonly content: string;
-        readonly providerOptions?: unknown;
-    } | {
-        readonly role: "assistant";
-        readonly content: readonly ({
-            readonly type: "text";
-            readonly text: string;
-            readonly providerOptions?: unknown;
-        } | {
-            readonly type: "reasoning";
-            readonly text: string;
-            readonly providerOptions?: unknown;
-        } | {
-            readonly type: "tool-call";
-            readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
-            readonly toolName: string;
-            readonly input: unknown;
-            readonly providerOptions?: unknown;
-            readonly providerExecuted?: boolean | undefined;
-        })[];
-        readonly providerOptions?: unknown;
-    } | {
-        readonly role: "tool";
-        readonly content: readonly {
-            readonly type: "tool-result";
-            readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
-            readonly toolName: string;
-            readonly output: unknown;
-            readonly providerOptions?: unknown;
-            readonly isError?: boolean | undefined;
-        }[];
-        readonly providerOptions?: unknown;
-    })[];
-    outcome: "ok" | "partial";
-    reason: "completed" | "step-cap" | "degenerate-loop";
-}, import("effect/ai/AiError").AiError, ConversationStore | import("effect/ai/LanguageModel").LanguageModel | Exclude<Exclude<Exclude<Exclude<R, import("effect/Tracer").ParentSpan>, never>, import("effect/Tracer").ParentSpan>, never> | Exclude<Exclude<Exclude<Exclude<Tool.HandlersFor<Tools>, import("effect/Tracer").ParentSpan>, never>, import("effect/Tracer").ParentSpan>, never>>;

package/dist/runAgent.js

@@ -1,63 +0,0 @@
-import { Effect, Option, Ref } from "effect";
-import { ConversationStore } from "@xandreed/core";
-import { CurrentPromptCacheKey } from "@xandreed/core";
-import { CurrentModelCallPolicy } from "@xandreed/core";
-import { handoffToMessage, safeKeepFrom } from "@xandreed/core";
-import { runLoop } from "./loop.js";
-const COMPACT_COOLDOWN_TURNS = 3;
-export const runAgent = (config, conversationId, userMessage, options) => Effect.gen(function* () {
-  const store = yield* ConversationStore;
-  yield* store.append(conversationId, { role: "user", content: userMessage.text }).pipe(Effect.orDie);
-  const fold = yield* store.latestCheckpoint(conversationId).pipe(Effect.orDie), active = yield* store.listActive(conversationId).pipe(Effect.orDie), messages = Option.match(fold, {
-    onNone: () => active.map((row) => row.message),
-    onSome: (checkpoint) => [
-      handoffToMessage(checkpoint.summary),
-      ...active.map((row) => row.message)
-    ]
-  }), activePositions = active.map((row) => Option.some(row.position)), mirrorRef = yield* Ref.make(Option.isSome(fold) ? [Option.none(), ...activePositions] : activePositions), cooldownRef = yield* Ref.make(0), onTail = (tail) => store.appendAll(conversationId, tail).pipe(Effect.tap((positions) => Ref.update(mirrorRef, (all) => [...all, ...positions.map(Option.some)])), Effect.orDie), compactWith = (policy) => (buffer, lastTurnUsage) => Effect.gen(function* () {
-    const cooldown = yield* Ref.get(cooldownRef);
-    if (cooldown > 0) {
-      yield* Ref.set(cooldownRef, cooldown - 1);
-      return Option.none();
-    }
-    if (lastTurnUsage.inputTokens <= policy.thresholdTokens)
-      return Option.none();
-    const cut = safeKeepFrom(buffer, policy.keepTurns);
-    if (Option.isNone(cut))
-      return Option.none();
-    const mirror = yield* Ref.get(mirrorRef);
-    if (mirror.length !== buffer.length)
-      return Option.none();
-    const covered = mirror.slice(0, cut.value).flatMap(Option.toArray), coveredPosition = covered[covered.length - 1], firstKept = mirror.slice(cut.value).flatMap(Option.toArray)[0];
-    if (coveredPosition === void 0 || firstKept !== void 0 && coveredPosition >= firstKept)
-      return Option.none();
-    const previous = yield* store.latestCheckpoint(conversationId).pipe(Effect.map(Option.map((checkpoint) => checkpoint.summary))), summary = (yield* policy.summarize(buffer, previous)).trim();
-    if (summary.length === 0)
-      return Option.none();
-    yield* store.checkpointAt(conversationId, summary, coveredPosition);
-    yield* Ref.set(mirrorRef, [Option.none(), ...mirror.slice(cut.value)]);
-    yield* Ref.set(cooldownRef, COMPACT_COOLDOWN_TURNS);
-    return Option.some({ summary, keepFrom: cut.value });
-  }).pipe(Effect.withSpan("engine.compact"), Effect.catch(() => Effect.succeed(Option.none()))), result = yield* runLoop({
-    system: config.system,
-    messages,
-    toolkit: config.toolkit,
-    ...config.maxSteps !== void 0 ? { maxSteps: config.maxSteps } : {},
-    ...config.toolConcurrency !== void 0 ? { toolConcurrency: config.toolConcurrency } : {},
-    ...config.pollableTools !== void 0 ? { pollableTools: config.pollableTools } : {},
-    ...options?.onEvent !== void 0 ? { onEvent: options.onEvent } : {},
-    ...options?.pendingInput !== void 0 ? { pendingInput: options.pendingInput } : {},
-    ...config.compaction !== void 0 ? { compact: compactWith(config.compaction) } : {},
-    ...config.streaming !== void 0 ? { streaming: config.streaming } : {},
-    onTail
-  }).pipe(Effect.provideService(CurrentPromptCacheKey, Option.some(config.promptCacheKey ?? String(conversationId))));
-  yield* store.recordOutcome(conversationId, result.outcome, result.reason).pipe(Effect.catch((error) => Effect.logWarning(`the run's outcome was not recorded: ${error.message}`)));
-  return result;
-}).pipe(Effect.withSpan("agent.run", {
-  attributes: {
-    "agent.kind": "run",
-    "agent.conversation_id": String(conversationId),
-    "agent.userMessage": options?.traceContent === !0 ? userMessage.text.slice(0, 500) : "[redacted]",
-    "agent.userMessage_chars": userMessage.text.length
-  }
-}), Effect.provideService(CurrentModelCallPolicy, Option.fromNullishOr(config.modelPolicy)));

package/dist/runAgent.test.d.ts

@@ -1 +0,0 @@
-export {};