@xandreed/plugin-agent-loop 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xand Reed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./loop.js";
+export * from "./runAgent.js";
+export { agentLoopPlugin, default } from "./plugin.adapter.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./loop.js";
+export * from "./runAgent.js";
+export { agentLoopPlugin, default } from "./plugin.adapter.js";

package/dist/loop.d.ts

@@ -0,0 +1,193 @@
+import { LanguageModel, Prompt } from "@effect/ai";
+import type { Tool, Toolkit } from "@effect/ai";
+import { Effect, Option } from "effect";
+import type { LoopEvent } from "@xandreed/core";
+import type { AgentMessage } from "@xandreed/core";
+import type { TokenUsage } from "@xandreed/core";
+/**
+ * A mid-run fold the `compact` callback hands back: everything before
+ * `keepFrom` is replaced by `handoffToMessage(summary)`; `messages[keepFrom..]`
+ * survive verbatim. CONTRACT: `keepFrom` must index an assistant message
+ * (never split a tool-call from its results) — `safeKeepFrom` guarantees it;
+ * the loop ignores a plan that violates the contract (the run continues
+ * unfolded, best-effort).
+ */
+export interface CompactionPlan {
+    readonly summary: string;
+    readonly keepFrom: number;
+}
+/**
+ * The provider-agnostic agent loop. `@effect/ai` resolves ONE step's tool
+ * calls (its handlers are our Effects) but does not iterate across turns —
+ * iteration is ours: each turn maps the message buffer to a `Prompt`, calls
+ * `LanguageModel.generateText`, appends the response as the new tail, and
+ * re-invokes until the model stops requesting tools, `maxSteps` is hit, or
+ * the degenerate-loop breaker fires. State is an immutable fold through
+ * `Effect.iterate` — the same discipline as foundry's forge loop.
+ */
+export interface RunLoopOptions<Tools extends Record<string, Tool.Any>, 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. */
+    readonly captureTraceContent?: boolean;
+    readonly messages: ReadonlyArray<AgentMessage>;
+    readonly toolkit: Toolkit.Toolkit<Tools>;
+    /** Run-pinned deterministic capability selection, refreshed between steps.
+     * A capability-expansion tool can update this selection for the next call.
+     * Handlers must still enforce their own principal/action policy. */
+    /** Host completion condition, checked after settled tools/events. Avoids a
+     * paid final prose call when a tool already delivered the complete result. */
+    readonly isComplete?: () => Effect.Effect<boolean, never, R>;
+    /** When true, a model stop cannot substitute for host completion. A bounded
+     * corrective turn asks for the missing actions; maxSteps still applies. */
+    readonly requireCompletion?: boolean;
+    readonly activeTools?: () => Effect.Effect<ReadonlyArray<keyof Tools>, never, R>;
+    /** A ceiling, not a target — a normal run ends when the model stops
+     *  calling tools. Default {@link DEFAULT_MAX_STEPS}. */
+    readonly maxSteps?: number;
+    /** Concurrency for resolving one step's tool calls. Default
+     *  {@link DEFAULT_TOOL_CONCURRENCY} — bounded so a many-call turn doesn't
+     *  stampede the provider. */
+    readonly toolConcurrency?: number;
+    /** Tools designed to be POLLED — repeat calls with unchanged results are
+     *  correct for these, so they never count toward the degenerate breaker. */
+    readonly pollableTools?: ReadonlyArray<string>;
+    /** The single event sink — see `LoopEvent`. */
+    readonly onEvent?: (event: LoopEvent) => Effect.Effect<void, never, R>;
+    /**
+     * Incremental persistence: called with each turn's appended messages
+     * (model responses AND synthetic correctives) the moment they land, so a
+     * session is restorable to its last completed turn after a crash. Returns
+     * the absolute store positions aligned with the input.
+     */
+    readonly onTail?: (messages: ReadonlyArray<AgentMessage>) => Effect.Effect<ReadonlyArray<number>, never, R>;
+    /**
+     * The WITHIN-RUN compaction seam, consulted at turn boundaries while the
+     * run continues. Receives the buffer the NEXT turn would send plus the
+     * just-finished turn's usage (its `inputTokens` IS the live context cost);
+     * `Some(plan)` rewrites the buffer to summary + kept tail. The loop stays
+     * pure — the callback owns thresholds, summarization, and persistence.
+     */
+    readonly compact?: (messages: ReadonlyArray<AgentMessage>, lastTurnUsage: TokenUsage) => Effect.Effect<Option.Option<CompactionPlan>, never, R>;
+    /**
+     * Route turns through `streamText`, folding the parts back into the
+     * settled turn shape while fanning `assistant_delta` events as tokens
+     * flow. Default FALSE. A stream that fails before its first part
+     * (scripted providers' `Stream.die` included) falls back to
+     * `generateText` transparently — for the REST of the run, not per turn.
+     */
+    readonly streaming?: boolean;
+    /**
+     * MID-TURN steering, consulted at turn boundaries while the run
+     * continues (the `compact` seam's twin): `Some(text)` appends a user
+     * message the NEXT model call sees — a human's course correction lands
+     * at the next step instead of after the whole run. Injected after any
+     * fold (steering must never be compacted away) and persisted via
+     * `onTail` like every other appended message.
+     */
+    readonly pendingInput?: () => Effect.Effect<Option.Option<string>, never, R>;
+}
+export declare const DEFAULT_MAX_STEPS = 100;
+export declare const DEFAULT_TOOL_CONCURRENCY = 4;
+export declare const DEGENERATE_REPEAT_NUDGE: string;
+export declare const DEGENERATE_LOOP_STOP = "[stopped: repeated the same tool call with no progress \u2014 the run was looping]";
+export type Phase = "continue" | "completed" | "step-cap" | "degenerate-loop";
+/**
+ * The degenerate-loop breaker's fold over one turn's progress signature —
+ * PURE, so the nudge-at-3 / break-at-5 policy is tested without a scripted
+ * model. An empty signature (no tool calls, or only pollable ones) leaves
+ * the count untouched: a turn that did nothing is not a turn that repeated.
+ */
+export declare const foldProgress: (state: {
+    readonly seen: ReadonlySet<string>;
+    readonly staleTurns: number;
+}, sig: string) => {
+    readonly stale: number;
+    readonly seen: ReadonlySet<string>;
+    readonly nudge: boolean;
+    readonly broke: boolean;
+};
+/** THE decision after a turn — the only model-driven edge is `wantsMore`
+ *  (the provider said "tool-calls" and there were some); the breaker and
+ *  the cap are the harness's, and they outrank it in that order. */
+export declare const nextPhase: (facts: {
+    readonly broke: boolean;
+    readonly wantsMore: boolean;
+    readonly turnIndex: number;
+    readonly maxSteps: number;
+}) => Phase;
+export declare const runLoop: <Tools extends Record<string, Tool.Any>, R = never>(options: RunLoopOptions<Tools, R>) => Effect.Effect<{
+    finalText: string;
+    messages: readonly ({
+        readonly providerOptions?: unknown;
+        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 providerOptions?: unknown;
+            readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
+            readonly toolName: string;
+            readonly input: unknown;
+            readonly providerExecuted?: boolean | undefined;
+        })[];
+    } | {
+        readonly providerOptions?: unknown;
+        readonly role: "tool";
+        readonly content: readonly {
+            readonly type: "tool-result";
+            readonly providerOptions?: unknown;
+            readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
+            readonly toolName: string;
+            readonly output: unknown;
+            readonly isError?: boolean | undefined;
+        }[];
+    })[];
+    newTail: readonly ({
+        readonly providerOptions?: unknown;
+        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 providerOptions?: unknown;
+            readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
+            readonly toolName: string;
+            readonly input: unknown;
+            readonly providerExecuted?: boolean | undefined;
+        })[];
+    } | {
+        readonly providerOptions?: unknown;
+        readonly role: "tool";
+        readonly content: readonly {
+            readonly type: "tool-result";
+            readonly providerOptions?: unknown;
+            readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
+            readonly toolName: string;
+            readonly output: unknown;
+            readonly isError?: boolean | undefined;
+        }[];
+    })[];
+    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>>;

package/dist/loop.js

@@ -0,0 +1,231 @@
+import { 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";
+import { CurrentEmptyResponseTolerance } from "@xandreed/core";
+import { addUsage, zeroUsage } from "@xandreed/core";
+import { extractModel, extractUsage, handoffToMessage, responseReasoning, responseText, responseToAgentMessages, responseToolCalls, responseToolResults, toPromptMessages, withToolCallIds, withUsageOnAssistant } from "@xandreed/core";
+export const DEFAULT_MAX_STEPS = 100, DEFAULT_TOOL_CONCURRENCY = 4;
+const engineRuns = Metric.counter("engine.runs", {
+  description: "agent runs by outcome and reason",
+  incremental: !0
+}), engineToolCalls = Metric.counter("engine.tool_calls", {
+  description: "tool calls by tool name and result",
+  incremental: !0
+}), engineCorrections = Metric.counter("engine.corrections", {
+  description: "self-corrections by kind (malformed recovery, degenerate nudge)",
+  incremental: !0
+}), tagged = (metric, tags) => Object.entries(tags).reduce((m, [key, value]) => Metric.tagged(m, key, value), metric), MAX_MALFORMED = 3, REPEAT_NUDGE_AT = 3, REPEAT_BREAK_AT = 5;
+export const DEGENERATE_REPEAT_NUDGE = "You've called the same tool(s) and gotten the same result several times in " + "a row \u2014 you're looping without making progress. STOP repeating that call. " + "Take a DIFFERENT concrete action toward the task; if you're genuinely stuck, say what's blocking you and stop.", DEGENERATE_LOOP_STOP = "[stopped: repeated the same tool call with no progress \u2014 the run was looping]";
+const clip = (s, max) => s.length <= max ? s : `${s.slice(0, max)}\u2026`, progressSignature = (content, pollable) => {
+  const calls = responseToolCalls(content);
+  if (calls.length === 0)
+    return "";
+  if (calls.every((c) => pollable.has(c.toolName)))
+    return "";
+  return responseToolResults(content).filter((r) => !pollable.has(r.toolName)).map((r) => `${r.toolName}:${r.ok ? "ok" : "err"}:${clip(JSON.stringify(r.result ?? null), 300)}`).sort().join("|");
+};
+export const foldProgress = (state, sig) => {
+  const stale = sig === "" ? state.staleTurns : state.seen.has(sig) ? state.staleTurns + 1 : 0, seen = sig === "" || state.seen.has(sig) ? state.seen : new Set([...state.seen, sig]);
+  return {
+    stale,
+    seen,
+    nudge: sig !== "" && stale === REPEAT_NUDGE_AT,
+    broke: sig !== "" && stale >= REPEAT_BREAK_AT
+  };
+}, nextPhase = (facts) => facts.broke ? "degenerate-loop" : !facts.wantsMore ? "completed" : facts.turnIndex >= facts.maxSteps ? "step-cap" : "continue", runLoop = (options) => Effect.gen(function* () {
+  yield* Effect.annotateCurrentSpan({ "engine.input.messages": options.messages.length });
+  const maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS, pollable = new Set(options.pollableTools ?? []), eventContext = yield* Effect.context(), onEvent = (event) => Effect.gen(function* () {
+    const parent = yield* Effect.currentSpan.pipe(Effect.orDie);
+    yield* (options.onEvent?.(event) ?? Effect.void).pipe(Effect.withParentSpan(parent), Effect.provide(eventContext));
+  }), toolkit = yield* options.toolkit, step = (state) => Effect.gen(function* () {
+    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)));
+    if (options.captureTraceContent === !0)
+      yield* Effect.annotateCurrentSpan({
+        "engine.step.input": JSON.stringify({ messages: prompt.content, activeTools: toolNames })
+      });
+    const toolSequence = yield* Ref.make(0), callOptions = {
+      prompt,
+      toolkit: {
+        tools: selectedTools,
+        handle: (name, params) => Effect.gen(function* () {
+          const sequence = yield* Ref.getAndUpdate(toolSequence, (value) => value + 1), toolCallId = `execution:${state.turnIndex}:${sequence}`;
+          yield* onEvent({ type: "tool_start", turnIndex: state.turnIndex, toolCallId, toolName: String(name), args: params });
+          return yield* toolkit.handle(name, params).pipe(Effect.tap((result) => onEvent({
+            type: "tool_end",
+            turnIndex: state.turnIndex,
+            toolCallId,
+            toolName: String(name),
+            args: params,
+            ok: !result.isFailure,
+            result: result.result
+          })));
+        })
+      },
+      concurrency: options.toolConcurrency ?? DEFAULT_TOOL_CONCURRENCY
+    }, settled = (streamingHealthy) => 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({
+        type: "assistant_delta",
+        turnIndex: state.turnIndex,
+        channel: delta.channel,
+        id: delta.id,
+        delta: delta.delta,
+        ...delta.toolName === void 0 ? {} : { toolName: delta.toolName }
+      })).pipe(Effect.map((turn) => Option.some({
+        _tag: "ok",
+        content: turn.content,
+        finishReason: turn.finishReason,
+        usage: turn.usage,
+        streamingHealthy: !0
+      })), Effect.catchAll((err) => Ref.get(partSeen).pipe(Effect.flatMap((armed) => armed ? Effect.fail(err) : Effect.succeed(Option.none())))), Effect.catchAllDefect((defect) => Ref.get(partSeen).pipe(Effect.flatMap((armed) => armed ? Effect.die(defect) : Effect.succeed(Option.none())))));
+      return yield* Option.match(folded, {
+        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));
+    if (outcome._tag === "malformed") {
+      const streak = state.malformedStreak + 1;
+      if (streak >= MAX_MALFORMED)
+        return yield* Effect.fail(outcome.err);
+      const desc = clip(String(outcome.err.description ?? "the response could not be parsed"), 600);
+      yield* Effect.logWarning(`recovering from a malformed response: ${desc}`);
+      yield* Metric.increment(tagged(engineCorrections, { "engine.kind": "malformed" }));
+      const corrective = {
+        role: "user",
+        content: `Your previous reply could not be parsed: ${desc}
+
+This usually means you called a tool that doesn't exist or used the wrong argument shape. The only tools available are: ${toolNames.join(", ")}. Reply again using one of those tools, or plain text if you're done.`
+      };
+      yield* options.onTail?.([corrective]) ?? Effect.void;
+      const recoveredIndex = state.turnIndex + 1, capped = recoveredIndex >= maxSteps;
+      yield* capped ? Effect.logWarning("step cap reached while recovering from a malformed response") : Effect.void;
+      return {
+        ...state,
+        messages: [...state.messages, corrective],
+        newTail: [...state.newTail, corrective],
+        turnIndex: recoveredIndex,
+        malformedStreak: streak,
+        corrections: state.corrections + 1,
+        phase: capped ? "step-cap" : state.phase
+      };
+    }
+    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),
+      ...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);
+    yield* onEvent({
+      type: "assistant_message",
+      turnIndex: state.turnIndex,
+      text,
+      reasoning: responseReasoning(content),
+      toolCalls,
+      usage,
+      ...Option.match(model, { onNone: () => ({}), onSome: (id) => ({ model: id }) }),
+      ...Option.match(assistantPosition, {
+        onNone: () => ({}),
+        onSome: (position) => ({ position })
+      })
+    });
+    const toolResults = responseToolResults(content);
+    yield* Effect.forEach(toolResults, (tr) => Metric.increment(tagged(engineToolCalls, {
+      "engine.tool": tr.toolName,
+      "engine.ok": tr.ok ? "true" : "false"
+    })));
+    const sig = progressSignature(content, pollable), progress = foldProgress(state, sig), { stale, seen } = progress, nudge = progress.nudge ? [{ role: "user", content: DEGENERATE_REPEAT_NUDGE }] : [];
+    yield* nudge.length > 0 ? options.onTail?.(nudge) ?? Effect.void : Effect.void;
+    yield* nudge.length > 0 ? Metric.increment(tagged(engineCorrections, { "engine.kind": "degenerate-nudge" })) : Effect.void;
+    const finalText = text.length > 0 ? text : state.finalText, turnIndex = state.turnIndex + 1, completed = yield* options.isComplete?.() ?? Effect.succeed(!1), requireMore = !completed && options.requireCompletion === !0, completionNudge = requireMore && toolCalls.length === 0 ? [{ role: "user", content: "The host reports that required actions are incomplete. Your ordinary text is not a delivered result. Complete the requested work using the available tools, or use an explicit supported failure/clarification action if the evidence is missing." }] : [];
+    yield* completionNudge.length > 0 ? options.onTail?.(completionNudge) ?? Effect.void : Effect.void;
+    const wantsMore = !completed && (requireMore || outcome.finishReason === "tool-calls" && toolCalls.length > 0), broke = progress.broke, phase = nextPhase({ broke, wantsMore, turnIndex, maxSteps });
+    yield* broke ? Effect.logWarning(`breaking a degenerate tool-call loop after ${stale} stale turns`) : Effect.void;
+    const nextMessages = [...state.messages, ...tail, ...nudge, ...completionNudge], plan = phase === "continue" && options.compact !== void 0 ? yield* options.compact(nextMessages, usage) : Option.none(), applied = Option.filter(plan, (p) => p.keepFrom > 0 && p.keepFrom < nextMessages.length && nextMessages[p.keepFrom]?.role === "assistant");
+    yield* Option.match(applied, {
+      onNone: () => Effect.void,
+      onSome: (p) => onEvent({
+        type: "compaction",
+        turnIndex: state.turnIndex,
+        tokens: usage.inputTokens,
+        kept: nextMessages.length - p.keepFrom
+      })
+    });
+    const steered = phase === "continue" && options.pendingInput !== void 0 ? yield* options.pendingInput() : Option.none(), steerTail = Option.match(steered, {
+      onNone: () => [],
+      onSome: (text) => [{ role: "user", content: text }]
+    });
+    yield* steerTail.length > 0 ? options.onTail?.(steerTail) ?? Effect.void : Effect.void;
+    return {
+      messages: [
+        ...Option.match(applied, {
+          onNone: () => nextMessages,
+          onSome: (p) => [handoffToMessage(p.summary), ...nextMessages.slice(p.keepFrom)]
+        }),
+        ...steerTail
+      ],
+      newTail: [...state.newTail, ...tail, ...nudge, ...completionNudge, ...steerTail],
+      finalText: broke && finalText.length === 0 ? DEGENERATE_LOOP_STOP : finalText,
+      turnIndex,
+      malformedStreak: 0,
+      seen,
+      staleTurns: stale,
+      usage: addUsage(state.usage, usage),
+      phase,
+      toolCalls: state.toolCalls + toolCalls.length,
+      toolFailures: state.toolFailures + toolResults.filter((tr) => !tr.ok).length,
+      corrections: state.corrections + (nudge.length > 0 ? 1 : 0),
+      streamingHealthy: outcome.streamingHealthy
+    };
+  }).pipe(Effect.onExit((exit) => onEvent({ type: "turn_end", turnIndex: state.turnIndex, status: Exit.isSuccess(exit) ? "completed" : Cause.isInterruptedOnly(exit.cause) ? "cancelled" : "failed" })), Effect.locally(CurrentAgentStep, Option.some(state.turnIndex)), Effect.withSpan("engine.turn", {
+    attributes: { "engine.turn": state.turnIndex, "engine.step": state.turnIndex + 1 }
+  })), final = yield* Effect.iterate({
+    messages: options.messages,
+    newTail: [],
+    finalText: "",
+    turnIndex: 0,
+    malformedStreak: 0,
+    seen: new Set,
+    staleTurns: 0,
+    usage: zeroUsage,
+    phase: "continue",
+    toolCalls: 0,
+    toolFailures: 0,
+    corrections: 0,
+    streamingHealthy: !0
+  }, { while: (state) => state.phase === "continue", body: step }), { outcome, reason } = Match.value(final.phase).pipe(Match.when("completed", () => ({ outcome: "ok", reason: "completed" })), Match.when("step-cap", () => ({
+    outcome: "partial",
+    reason: "step-cap"
+  })), Match.when("degenerate-loop", () => ({
+    outcome: "partial",
+    reason: "degenerate-loop"
+  })), Match.when("continue", () => ({ outcome: "ok", reason: "completed" })), Match.exhaustive);
+  yield* onEvent({ type: "agent_end", outcome, reason, finalText: final.finalText });
+  yield* Metric.increment(tagged(engineRuns, { "engine.outcome": outcome, "engine.reason": reason }));
+  yield* Effect.annotateCurrentSpan({
+    "engine.outcome": outcome,
+    "engine.reason": reason,
+    "engine.turns": final.turnIndex,
+    "engine.usage.total_tokens": final.usage.totalTokens,
+    "engine.tool_calls": final.toolCalls,
+    "engine.tool_calls.failed": final.toolFailures,
+    "engine.corrections": final.corrections,
+    error: outcome !== "ok"
+  });
+  return {
+    finalText: final.finalText,
+    messages: final.messages,
+    newTail: final.newTail,
+    outcome,
+    reason
+  };
+}).pipe(Effect.withSpan("engine.run"));

package/dist/loop.test.d.ts

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

package/dist/plugin.adapter.d.ts

@@ -0,0 +1,2 @@
+export declare const agentLoopPlugin: import("@xandreed/core").Plugin;
+export default agentLoopPlugin;

package/dist/plugin.adapter.js

@@ -0,0 +1,54 @@
+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.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",
+  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.decodeUnknown(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.prompt), 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.prompt }] } });
+      const position = yield* Ref.make(previous.length + 1), cooldown = yield* Ref.make(0), result = yield* runLoop({
+        system,
+        messages: [...previous, { role: "user", content: input.prompt }],
+        toolkit: tools.toolkit,
+        ...config,
+        pendingInput: () => input.steering.pipe(Effect.orDie),
+        onTail: (messages) => input.publish({ name: "messages", runId: input.runId, data: { messages } }).pipe(Effect.zipRight(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.catchAll((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

@@ -0,0 +1,140 @@
+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";
+/**
+ * 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 prompt, 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, prompt: string, 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>;
+    /** Prompt content 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 providerOptions?: unknown;
+        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 providerOptions?: unknown;
+            readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
+            readonly toolName: string;
+            readonly input: unknown;
+            readonly providerExecuted?: boolean | undefined;
+        })[];
+    } | {
+        readonly providerOptions?: unknown;
+        readonly role: "tool";
+        readonly content: readonly {
+            readonly type: "tool-result";
+            readonly providerOptions?: unknown;
+            readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
+            readonly toolName: string;
+            readonly output: unknown;
+            readonly isError?: boolean | undefined;
+        }[];
+    })[];
+    newTail: readonly ({
+        readonly providerOptions?: unknown;
+        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 providerOptions?: unknown;
+            readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
+            readonly toolName: string;
+            readonly input: unknown;
+            readonly providerExecuted?: boolean | undefined;
+        })[];
+    } | {
+        readonly providerOptions?: unknown;
+        readonly role: "tool";
+        readonly content: readonly {
+            readonly type: "tool-result";
+            readonly providerOptions?: unknown;
+            readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
+            readonly toolName: string;
+            readonly output: unknown;
+            readonly isError?: boolean | undefined;
+        }[];
+    })[];
+    outcome: "ok" | "partial";
+    reason: "completed" | "step-cap" | "degenerate-loop";
+}, import("@effect/ai/AiError").AiError, ConversationStore | import("@effect/ai/LanguageModel").LanguageModel | Exclude<Exclude<R, import("effect/Tracer").ParentSpan>, import("effect/Tracer").ParentSpan> | Exclude<Exclude<Tool.HandlersFor<Tools>, import("effect/Tracer").ParentSpan>, import("effect/Tracer").ParentSpan>>;

package/dist/runAgent.js

@@ -0,0 +1,63 @@
+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, prompt, options) => Effect.gen(function* () {
+  const store = yield* ConversationStore;
+  yield* store.append(conversationId, { role: "user", content: prompt }).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.catchAll(() => 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.locally(CurrentPromptCacheKey, Option.some(config.promptCacheKey ?? String(conversationId))));
+  yield* store.recordOutcome(conversationId, result.outcome, result.reason).pipe(Effect.catchAll((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.prompt": options?.traceContent === !0 ? prompt.slice(0, 500) : "[redacted]",
+    "agent.prompt_chars": prompt.length
+  }
+}), Effect.locally(CurrentModelCallPolicy, Option.fromNullable(config.modelPolicy)));

package/dist/runAgent.test.d.ts

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

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@xandreed/plugin-agent-loop",
+  "version": "0.3.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@xandreed/core": "0.3.0",
+    "@effect/ai": "0.35.0",
+    "effect": "3.21.4"
+  },
+  "private": false,
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "skills",
+    "profiles",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "license": "MIT"
+}