@ap3x/agent-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AP3X
+
+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,29 @@
+# @ap3x/agent-core
+
+The native agent runtime: a tool-calling loop, a conversation memory substrate, durable sessions, and context compaction — plus the `AgentBackend` seam orchestration builds on.
+
+Part of [AP3X](https://github.com/AP3X-Dev/AP3X) — a TypeScript multi-agent framework.
+
+## Install
+
+```bash
+npm install @ap3x/agent-core
+```
+
+## What's inside
+
+- **`runAgentLoop`** — the tool-calling agent loop with typed events.
+- **`Conversation`** — the append-only transcript every orchestrator reads and writes, with JSON/YAML persistence, token-budget management, and durable memory files.
+- **Compaction** — automatic context compaction with summary threading across runs.
+- **`defineTool`** — explicit TypeBox parameter schemas; no runtime reflection.
+- **Sessions** — durable session storage with resume and fork.
+- **`AgentBackend`** — the interface orchestration depends on, so runtimes stay swappable.
+- **Typed errors** — a single `AgentError` hierarchy with stable machine-readable codes.
+
+## Documentation
+
+See the [AP3X repository](https://github.com/AP3X-Dev/AP3X) for architecture notes, the full package map, and examples.
+
+## License
+
+MIT

package/dist/agent-errors.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The `AgentError` hierarchy.
+ *
+ * The orchestration layer (`@ap3x/swarms`) and the swarms-facing `Agent`
+ * wrapper raise these for failures that originate inside a single agent's
+ * lifecycle (initialization, LLM calls, tool execution, memory, MCP). They
+ * form one taxonomy under AP3X names and follow
+ * the same `Ap3xError` contract as the rest of the package: every error
+ * carries a stable, machine-readable `code` (and an optional `cause`).
+ */
+/** Stable codes for the agent error hierarchy. */
+export type AgentErrorCode = "agent" | "agent_initialization" | "agent_run" | "agent_llm" | "agent_tool" | "agent_memory" | "agent_mcp_connection" | "agent_mcp_tool";
+/**
+ * Base class for every agent error.
+ *
+ * This is a sibling taxonomy to {@link import("./errors").Ap3xError}: it keeps
+ * the same `code`/`cause` shape but is rooted here so the orchestration layer
+ * can `instanceof AgentError` across the whole family.
+ */
+export declare class AgentError extends Error {
+    /** Machine-readable, stable error code. */
+    readonly code: AgentErrorCode;
+    readonly cause?: unknown;
+    constructor(message: string, code?: AgentErrorCode, cause?: unknown);
+}
+/** Raised when an agent fails to construct/validate its configuration. */
+export declare class AgentInitializationError extends AgentError {
+    constructor(message: string, cause?: unknown);
+}
+/** Raised when an agent's run loop fails. */
+export declare class AgentRunError extends AgentError {
+    constructor(message: string, cause?: unknown);
+}
+/** Raised when the underlying LLM call fails. */
+export declare class AgentLLMError extends AgentError {
+    constructor(message: string, cause?: unknown);
+}
+/** Raised when a tool invocation fails. */
+export declare class AgentToolError extends AgentError {
+    constructor(message: string, cause?: unknown);
+}
+/** Raised when the agent's memory/conversation substrate fails. */
+export declare class AgentMemoryError extends AgentError {
+    constructor(message: string, cause?: unknown);
+}
+/** Raised when connecting to an MCP server fails. */
+export declare class AgentMCPConnectionError extends AgentError {
+    constructor(message: string, cause?: unknown);
+}
+/** Raised when executing a tool served over MCP fails. */
+export declare class AgentMCPToolError extends AgentError {
+    constructor(message: string, cause?: unknown);
+}
+//# sourceMappingURL=agent-errors.d.ts.map

package/dist/agent-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-errors.d.ts","sourceRoot":"","sources":["../src/agent-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,kDAAkD;AAClD,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,sBAAsB,GACtB,WAAW,GACX,WAAW,GACX,YAAY,GACZ,cAAc,GACd,sBAAsB,GACtB,gBAAgB,CAAC;AAErB;;;;;;GAMG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,cAAwB,EAAE,KAAK,CAAC,EAAE,OAAO;CAM7E;AAED,0EAA0E;AAC1E,qBAAa,wBAAyB,SAAQ,UAAU;gBAC1C,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAG7C;AAED,6CAA6C;AAC7C,qBAAa,aAAc,SAAQ,UAAU;gBAC/B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAG7C;AAED,iDAAiD;AACjD,qBAAa,aAAc,SAAQ,UAAU;gBAC/B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAG7C;AAED,2CAA2C;AAC3C,qBAAa,cAAe,SAAQ,UAAU;gBAChC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAG7C;AAED,mEAAmE;AACnE,qBAAa,gBAAiB,SAAQ,UAAU;gBAClC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAG7C;AAED,qDAAqD;AACrD,qBAAa,uBAAwB,SAAQ,UAAU;gBACzC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAG7C;AAED,0DAA0D;AAC1D,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAG7C"}

package/dist/agent-loop.d.ts

@@ -0,0 +1,30 @@
+import type { AgentContext, AgentEvent, AgentEventSink, AgentLoopConfig, AgentMessage } from "./types";
+/**
+ * Default assistant-turn cap. Deliberately high (not `10`) so legitimate long
+ * tool runs are never silently truncated — while still bounding a runaway model
+ * against a true infinite loop. Callers can set a low `maxLoops` to cap
+ * explicitly, or `Infinity` to disable the guard entirely.
+ */
+export declare const DEFAULT_MAX_LOOPS = 1000;
+/**
+ * Run the turn cycle starting from a set of new prompt messages. Emits the full
+ * lifecycle and returns every NEW message produced (prompts + assistant turns +
+ * tool results). The loop stops when an assistant turn requests no tools, when
+ * a tool batch terminates, on an error/aborted stop reason, or at `maxLoops`.
+ */
+export declare function runAgentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal): Promise<AgentMessage[]>;
+/**
+ * Continue the loop from an existing context without injecting a new prompt.
+ * The last message must not be an assistant message (after a turn that produced
+ * tool results, the tail is a `toolResult`, which is a valid continuation).
+ */
+export declare function runAgentLoopContinue(context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal): Promise<AgentMessage[]>;
+/** A streamed view of a loop run: iterate {@link AgentEvent}s, await the result. */
+export interface AgentEventStream extends AsyncIterable<AgentEvent> {
+    result(): Promise<AgentMessage[]>;
+}
+/** Streaming wrapper over {@link runAgentLoop}. */
+export declare function agentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal): AgentEventStream;
+/** Streaming wrapper over {@link runAgentLoopContinue}, validated eagerly. */
+export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal): AgentEventStream;
+//# sourceMappingURL=agent-loop.d.ts.map

package/dist/agent-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../src/agent-loop.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACd,eAAe,EACf,YAAY,EAEb,MAAM,SAAS,CAAC;AAEjB;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AA6ItC;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,YAAY,EAAE,CAAC,CA+RzB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,YAAY,EAAE,CAAC,CAOzB;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAiB,SAAQ,aAAa,CAAC,UAAU,CAAC;IACjE,MAAM,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CACnC;AAwCD,mDAAmD;AACnD,wBAAgB,SAAS,CACvB,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,gBAAgB,CAElB;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,gBAAgB,CAOlB"}

package/dist/agent.d.ts

@@ -0,0 +1,160 @@
+import type { AssistantMessage, Model, SimpleStreamOptions, Usage } from "@ap3x/ai";
+import type { AgentEvent, AgentHooks, AgentMessage, AnyAgentTool, StreamFn, ThinkingLevel } from "./types";
+/** A live subscriber to {@link Agent} events; receives the run's abort signal. */
+export type AgentListener = (event: AgentEvent, signal: AbortSignal) => void | Promise<void>;
+/** Construction options for a stateful {@link Agent}. */
+export interface AgentOptions {
+    model: Model<string>;
+    systemPrompt?: string;
+    tools?: AnyAgentTool[];
+    reasoning?: Exclude<ThinkingLevel, "off">;
+    /**
+     * Initial transcript to seed the agent with. Seeds are CONTEXT-ONLY: the
+     * model sees them, but session-backed hosts ({@link AgentHarness#prompt},
+     * the CLI) persist only turn-PRODUCED messages, so a session resumed later
+     * reconstructs WITHOUT the seed. This is deliberate — resume paths seed
+     * `messages` from the session's own `buildContext()`, and persisting seeds
+     * would re-append the entire history to the session on every resume.
+     * Callers who want a seed to be durable must append it to the session
+     * themselves before prompting. (B21)
+     */
+    messages?: AgentMessage[];
+    maxLoops?: number;
+    toolExecution?: "sequential" | "parallel";
+    streamOptions?: SimpleStreamOptions;
+    hooks?: AgentHooks;
+    streamFn?: StreamFn;
+    sessionId?: string;
+    /** Auto-compact context when it nears the window. Default: enabled. */
+    autoCompact?: boolean;
+    /**
+     * Summary of a prior compaction (e.g. from the session this agent was seeded
+     * from). Threads into the loop so the next compaction merges into it instead
+     * of summarizing blind. Kept current across runs from `compaction` events.
+     */
+    previousSummary?: string;
+}
+/** Public, read-only snapshot of an agent's current state. */
+export interface AgentState {
+    systemPrompt?: string;
+    model: Model<string>;
+    /** A copy of the current transcript. */
+    messages: AgentMessage[];
+    /** A copy of the registered tools. */
+    tools: AnyAgentTool[];
+    isRunning: boolean;
+    errorMessage?: string;
+}
+/** Concatenate the text blocks of an assistant message into a single string. */
+export declare function finalTextOf(message: AssistantMessage | undefined): string;
+/** The last assistant message in a transcript, if any. */
+export declare function lastAssistant(messages: AgentMessage[]): AssistantMessage | undefined;
+/**
+ * A stateful agent that owns a transcript and a single active run at a time.
+ * `prompt()` appends a user message and drives the loop to completion;
+ * `continue()` resumes from the current transcript without a new prompt.
+ */
+export declare class Agent {
+    model: Model<string>;
+    systemPrompt?: string;
+    reasoning?: Exclude<ThinkingLevel, "off">;
+    maxLoops?: number;
+    toolExecution: "sequential" | "parallel";
+    streamOptions?: SimpleStreamOptions;
+    hooks: AgentHooks;
+    streamFn?: StreamFn;
+    sessionId?: string;
+    autoCompact?: boolean;
+    previousSummary?: string;
+    private toolList;
+    private transcript;
+    private running;
+    private controller?;
+    private lastError?;
+    private readonly listeners;
+    /**
+     * One shared FIFO of pending host-queued messages, each tagged with its
+     * {@link QueueMode}. `steer`-mode entries drain at each turn boundary
+     * (mid-run injection); everything left — `followUp`, `nextTurn`, and any
+     * late `steer` — drains when the run would otherwise stop (the rescue).
+     * JS is single-threaded, so enqueue is a plain push and drain is a plain
+     * splice at a loop boundary: no locking, no lost update.
+     */
+    private pending;
+    /** A never-aborted signal handed to listeners for out-of-run queue events. */
+    private readonly idleSignal;
+    constructor(options: AgentOptions);
+    /** A defensive snapshot of the agent's state. */
+    get state(): AgentState;
+    /** Whether a run is in progress. */
+    get isRunning(): boolean;
+    /** The abort signal of the active run, if any. */
+    get signal(): AbortSignal | undefined;
+    /** The full transcript (a copy). */
+    get messages(): AgentMessage[];
+    /** The registered tools (a copy). Setting replaces the list with a copy. */
+    get tools(): AnyAgentTool[];
+    set tools(tools: AnyAgentTool[]);
+    /** Register an event listener. Returns an unsubscribe function. */
+    subscribe(listener: AgentListener): () => void;
+    /**
+     * Queue a steering message. During a live run it is injected at the next turn
+     * boundary (before the next assistant turn streams); a steer queued during the
+     * final turn is rescued into the follow-up drain so it still extends the run.
+     * While idle it rides into the next run's first turn. Safe to call any time.
+     */
+    steer(message: AgentMessage): void;
+    /** Queue a follow-up message that extends the run once it would otherwise stop. */
+    followUp(message: AgentMessage): void;
+    /**
+     * Queue a next-turn message. At the Agent level this shares the follow-up
+     * drain (delivered when the run would stop); the mode tag is preserved on
+     * `queue_update` so a host/harness can apply richer next-prompt semantics.
+     */
+    nextTurn(message: AgentMessage): void;
+    /**
+     * Move every pending host-queued message (steer/followUp/nextTurn, in queue
+     * order, mode tags intact) from `source` into this agent's queue. Used when a
+     * host replaces its agent mid-conversation (e.g. a compaction reseed) so
+     * messages queued while idle survive the rebuild instead of being dropped.
+     */
+    adoptPendingFrom(source: Agent): void;
+    /** Abort the active run, if any. */
+    abort(): void;
+    /** Clear the transcript and any error state. Rejects while running. */
+    reset(): void;
+    /**
+     * Append a user prompt and run the loop to completion. Returns the final
+     * assistant message. Throws {@link AgentHarnessError} `busy` if already running.
+     */
+    prompt(input: string | AgentMessage | AgentMessage[]): Promise<AssistantMessage>;
+    /** Continue the loop from the current transcript with no new prompt. */
+    continue(): Promise<AssistantMessage>;
+    private normalizePrompts;
+    private currentContext;
+    private currentConfig;
+    /**
+     * Wire the shared pending queue into the loop's two drain hooks, COMPOSED
+     * with any user-supplied hooks (never clobbered): the queue is drained first,
+     * then the user's hook is consulted and appended. `getSteeringMessages`
+     * drains `steer`-mode entries (mid-run inject); `getFollowUpMessages` drains
+     * everything left — `followUp`, `nextTurn`, and any late `steer` (the rescue).
+     * When the queue is empty and the user set no hook, each returns `[]`, which
+     * the loop treats identically to an absent hook (byte-identical no-queue path).
+     */
+    private composedHooks;
+    /** Enqueue a pending message and notify observers via `queue_update`. */
+    private enqueue;
+    /** Remove and return (in FIFO order) the messages whose mode matches. */
+    private drainQueue;
+    /**
+     * Emit a `queue_update` snapshot to every listener. Best-effort and
+     * out-of-band: a failing observer is isolated so it can neither break an
+     * enqueue nor the active run. Uses the active run's signal when running, else
+     * a never-aborted idle signal.
+     */
+    private emitQueueUpdate;
+    private runWithLifecycle;
+}
+export type { Usage };
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/backend.d.ts

@@ -0,0 +1,67 @@
+import type { Model } from "@ap3x/ai";
+import { type AgentOptions } from "./agent";
+import { type AgentEventStream } from "./agent-loop";
+import type { AgentEvent, AgentMessage, StopReason, Usage } from "./types";
+/** Per-run options accepted by an {@link AgentBackend}. */
+export interface AgentRunOptions {
+    signal?: AbortSignal;
+}
+/** The uniform result every backend returns from a `run()`. */
+export interface AgentRunResult {
+    /** All NEW messages produced by the run (prompts + assistant turns + tool results). */
+    messages: AgentMessage[];
+    /** Concatenated text of the final assistant message. */
+    finalText: string;
+    /** Usage of the final assistant message. */
+    usage: Usage;
+    /** Why the run stopped. */
+    stopReason: StopReason;
+    /** Present when the run failed. */
+    errorMessage?: string;
+}
+/** Optional capabilities a backend can advertise via {@link AgentBackend.supports}. */
+export type BackendCapability = "stream" | "subscribe" | "abort" | "clone" | "tools";
+/**
+ * The load-bearing seam between AP3X orchestration and any agent runtime. The
+ * only required method is `run`; the rest are optional so simple backends can
+ * be tiny while richer ones expose streaming, eventing and cloning.
+ */
+export interface AgentBackend {
+    run(task: string | AgentMessage[], opts?: AgentRunOptions): Promise<AgentRunResult>;
+    runStream?(task: string | AgentMessage[], opts?: AgentRunOptions): AgentEventStream;
+    subscribe?(listener: (event: AgentEvent) => void | Promise<void>): () => void;
+    abort?(): void;
+    clone?(): AgentBackend;
+    supports?(capability: BackendCapability): boolean;
+    getCurrentModel?(): Model<string>;
+}
+/**
+ * The AP3X-native default backend. By default each `run()` is *ephemeral*: it
+ * spins up a fresh {@link Agent} over a snapshot of the configured transcript so
+ * concurrent runs don't share state. Pass `{ ephemeral: false }` to keep a
+ * single stateful agent across runs.
+ */
+export declare class Ap3xRuntimeBackend implements AgentBackend {
+    private readonly options;
+    private readonly ephemeral;
+    private stateful?;
+    private active?;
+    private readonly listeners;
+    constructor(options: AgentOptions & {
+        ephemeral?: boolean;
+    });
+    private newAgent;
+    private agentFor;
+    run(task: string | AgentMessage[], opts?: AgentRunOptions): Promise<AgentRunResult>;
+    runStream(task: string | AgentMessage[], opts?: AgentRunOptions): AgentEventStream;
+    subscribe(listener: (event: AgentEvent) => void | Promise<void>): () => void;
+    abort(): void;
+    clone(): AgentBackend;
+    supports(capability: BackendCapability): boolean;
+    getCurrentModel(): Model<string>;
+}
+/** Convenience factory mirroring the {@link Ap3xRuntimeBackend} constructor. */
+export declare function createRuntimeBackend(options: AgentOptions & {
+    ephemeral?: boolean;
+}): AgentBackend;
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAS,KAAK,YAAY,EAA8B,MAAM,SAAS,CAAC;AAC/E,OAAO,EAAE,KAAK,gBAAgB,EAAa,MAAM,cAAc,CAAC;AAEhE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAE3E,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,uFAAuF;IACvF,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,KAAK,EAAE,KAAK,CAAC;IACb,2BAA2B;IAC3B,UAAU,EAAE,UAAU,CAAC;IACvB,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,uFAAuF;AACvF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAErF;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACpF,SAAS,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,gBAAgB,CAAC;IACpF,SAAS,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC;IAC9E,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,KAAK,CAAC,IAAI,YAAY,CAAC;IACvB,QAAQ,CAAC,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAClD,eAAe,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;CACnC;AA6BD;;;;;GAKG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,CAAQ;IACzB,OAAO,CAAC,MAAM,CAAC,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0D;gBAExE,OAAO,EAAE,YAAY,GAAG;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE;IAM3D,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,QAAQ;IAMV,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAkCzF,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,gBAAgB;IA8BlF,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI;IAO5E,KAAK,IAAI,IAAI;IAIb,KAAK,IAAI,YAAY;IAIrB,QAAQ,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO;IAchD,eAAe,IAAI,KAAK,CAAC,MAAM,CAAC;CAGjC;AAED,gFAAgF;AAChF,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,YAAY,GAAG;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9C,YAAY,CAEd"}

package/dist/compaction.d.ts

@@ -0,0 +1,147 @@
+import type { AssistantMessage, Context, Model, SimpleStreamOptions } from "@ap3x/ai";
+import { CompactionError } from "./errors";
+import { type Result } from "./result";
+import type { AgentMessage, ThinkingLevel } from "./types";
+/** Tunables that govern when and how aggressively context is compacted. */
+export interface CompactionSettings {
+    enabled: boolean;
+    /** Tokens kept in reserve below the context window before compacting. */
+    reserveTokens: number;
+    /** Tokens of recent history to preserve uncompacted. */
+    keepRecentTokens: number;
+}
+export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
+/** Fractions of the context window that cap the fixed token levers on small models. */
+export declare const RESERVE_FRACTION = 0.15;
+export declare const KEEP_RECENT_FRACTION = 0.25;
+/**
+ * Clamp the fixed token levers to a fraction of the model's context window, so
+ * compaction stays possible on a small model. `reserveTokens`/`keepRecentTokens`
+ * are sized for large windows; left unscaled they push `compactionTier`'s
+ * post-swap floor above the line, so both tiers return "none" and compaction is
+ * silently inert on any window below ~49,491. Never raises a lever above its
+ * configured value, so any window >= 109,227 resolves byte-identically to the
+ * settings it was given. Pure: no wall-clock, no RNG. Guards a non-positive
+ * window by returning the settings unchanged.
+ */
+export declare function resolveCompactionSettings(settings: CompactionSettings, contextWindow: number): CompactionSettings;
+/**
+ * Resolve an `autoCompact` option to compaction settings: `false` disables
+ * compaction, `true`/`undefined` use the defaults.
+ */
+export declare function resolveAutoCompact(autoCompact?: boolean): CompactionSettings;
+/** System prompt used when asking the model to summarize prior context. */
+export declare const SUMMARIZATION_SYSTEM_PROMPT: string;
+/**
+ * Inflation applied to an estimate that has NO provider usage anchor. Plain
+ * chars/4 under-counts tool-call/JSON overhead and multibyte text, so a
+ * seeded/replayed transcript (the resume path) can read low and let the HARD
+ * line fire late — a provider rejection. With no ground truth we err high
+ * (~3.2 chars/token): the worst case of over-estimating is one early,
+ * overlapped SOFT summary call. Anchored estimates are exact provider counts
+ * and are never inflated.
+ */
+export declare const NO_ANCHOR_INFLATION = 1.25;
+/** Estimate the token cost of a single message (chars/4, images flat-rated). */
+export declare function estimateMessageTokens(message: AgentMessage): number;
+/**
+ * Estimate the token usage of a context. Prefers the provider-reported
+ * `usage.totalTokens` of the last successful assistant message, then adds a
+ * chars/4 estimate for every message after that point.
+ *
+ * `anchorFromIndex` restricts which assistants may anchor: only those at index
+ * >= the floor are eligible. After a compaction swap, every retained assistant's
+ * `totalTokens` still describes the OLD (uncompacted) context, so the loop
+ * passes the post-swap length as the floor; until a fresh post-swap assistant
+ * lands, the estimate falls back to the anchor-free chars/4 sum, inflated by
+ * {@link NO_ANCHOR_INFLATION}. Default 0 is byte-identical to the historical
+ * behavior for anchored contexts.
+ */
+export declare function estimateContextTokens(messages: AgentMessage[], anchorFromIndex?: number): number;
+/** Whether the context is large enough to warrant compaction. */
+export declare function shouldCompact(contextTokens: number, contextWindow: number, settings?: CompactionSettings): boolean;
+/** Fraction of the window at which a background (speculative) compaction starts. */
+export declare const SOFT_FRACTION = 0.6;
+/** Fraction of the window at which a blocking (emergency) compaction is required. */
+export declare const HARD_FRACTION = 0.85;
+/** The compaction urgency for a usage estimate: none, background, or emergency. */
+export type CompactionTier = "none" | "soft" | "hard";
+/**
+ * Decide the compaction tier for a usage estimate. Pure: no wall-clock, no RNG.
+ * HARD reuses `shouldCompact` as its reserve-line term — its first live call
+ * site — while `usage > HARD_FRACTION*window` adds large-window scaling. Each
+ * tier is gated on whether compaction can actually drop usage below the line:
+ * the post-swap floor is the kept recent tail plus the largest possible summary
+ * (`summaryMaxTokens` caps generation at 0.8*reserveTokens). If a swap cannot get
+ * under the line it would just re-trigger every turn, so we return "none" instead
+ * — killing perpetual per-turn summarization on small windows.
+ */
+export declare function compactionTier(usage: number, contextWindow: number, settings: CompactionSettings): CompactionTier;
+export interface CutPointResult {
+    /** Index into `messages` where the kept (recent) tail begins. */
+    cutIndex: number;
+    /** Estimated tokens of the kept tail. */
+    keptTokens: number;
+}
+/**
+ * Walk backward from the end accumulating tokens until `keepRecentTokens` is
+ * reached, then snap the cut to a turn boundary (a user or assistant message)
+ * so a tool result is never separated from the assistant turn that produced it.
+ */
+export declare function findCutPoint(messages: AgentMessage[], keepRecentTokens: number): CutPointResult;
+export interface CompactionResult {
+    summary: string;
+    /** The messages kept after the cut, ready to follow the summary. */
+    keptMessages: AgentMessage[];
+    tokensBefore: number;
+    /** Files read (and not later modified) across the compacted history. */
+    readFiles: string[];
+    /** Files written or edited across the compacted history. */
+    modifiedFiles: string[];
+}
+/** Prepared slices for a compaction run, independent of any LLM call. */
+export interface CompactionPreparation {
+    /** History summarized into the main summary (before any split turn). */
+    historyMessages: AgentMessage[];
+    /** Prefix of a turn split by the cut, summarized separately (empty if none). */
+    turnPrefixMessages: AgentMessage[];
+    /** Messages kept uncompacted after the cut. */
+    keptMessages: AgentMessage[];
+    /** Whether the cut lands inside a turn (kept tail starts mid-turn). */
+    isSplitTurn: boolean;
+    /** Estimated context tokens before compaction. */
+    tokensBefore: number;
+}
+/**
+ * Compute the cut point and the history / split-turn-prefix / kept slices for a
+ * message list. Pure: makes no LLM call. When the cut lands on an assistant
+ * message whose originating user turn is in the summarized history, the turn is
+ * "split" and its prefix is summarized separately from the older history.
+ */
+export declare function prepareCompaction(messages: AgentMessage[], settings?: CompactionSettings): CompactionPreparation;
+/** Injectable summary-generation call; defaults to `@ap3x/ai` `completeSimple`. */
+type CompleteFn = (model: Model<string>, context: Context, options?: SimpleStreamOptions) => Promise<AssistantMessage>;
+/**
+ * Summarize the older portion of a context and return the summary plus the
+ * recent tail. Uses the provider's `completeSimple` (overridable for tests via
+ * `options.complete`) with the summarization prompt. Deepens the base
+ * single-shot behavior with:
+ *   - iterative merge into a `previousSummary` (UPDATE_SUMMARIZATION),
+ *   - separate summarization of a split turn's prefix,
+ *   - a maxTokens cap (and reasoning support) on the generation call,
+ *   - read/modified file-operation tracking carried on the result + summary.
+ * Returns a {@link CompactionError} on failure rather than throwing.
+ */
+export declare function compact(messages: AgentMessage[], model: Model<string>, options?: {
+    settings?: CompactionSettings;
+    customInstructions?: string;
+    signal?: AbortSignal;
+    /** Previous compaction summary to merge into rather than regenerate. */
+    previousSummary?: string;
+    /** Reasoning level forwarded to the generation call when the model supports it. */
+    thinkingLevel?: ThinkingLevel;
+    /** Override for the summary-generation call (test seam). */
+    complete?: CompleteFn;
+}): Promise<Result<CompactionResult, CompactionError>>;
+export {};
+//# sourceMappingURL=compaction.d.ts.map

package/dist/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../src/compaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,OAAO,EAEP,KAAK,EACL,mBAAmB,EAEpB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,KAAK,MAAM,EAAoB,MAAM,UAAU,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE3D,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,eAAO,MAAM,2BAA2B,EAAE,kBAIzC,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,kBAAkB,EAC5B,aAAa,EAAE,MAAM,GACpB,kBAAkB,CAUpB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAI5E;AAED,2EAA2E;AAC3E,eAAO,MAAM,2BAA2B,QAIsC,CAAC;AAK/E;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAWxC,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAsBnE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,eAAe,SAAI,GAAG,MAAM,CA2B3F;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,EACrB,QAAQ,GAAE,kBAAgD,GACzD,OAAO,CAGT;AAED,oFAAoF;AACpF,eAAO,MAAM,aAAa,MAAM,CAAC;AACjC,qFAAqF;AACrF,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC,mFAAmF;AACnF,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEtD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,kBAAkB,GAC3B,cAAc,CAUhB;AAED,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,gBAAgB,EAAE,MAAM,GAAG,cAAc,CAsB/F;AAmCD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,YAAY,EAAE,YAAY,EAAE,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAoDD,yEAAyE;AACzE,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,eAAe,EAAE,YAAY,EAAE,CAAC;IAChC,gFAAgF;IAChF,kBAAkB,EAAE,YAAY,EAAE,CAAC;IACnC,+CAA+C;IAC/C,YAAY,EAAE,YAAY,EAAE,CAAC;IAC7B,uEAAuE;IACvE,WAAW,EAAE,OAAO,CAAC;IACrB,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,YAAY,EAAE,EACxB,QAAQ,GAAE,kBAAgD,GACzD,qBAAqB,CA0BvB;AAeD,mFAAmF;AACnF,KAAK,UAAU,GAAG,CAChB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EACpB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,mBAAmB,KAC1B,OAAO,CAAC,gBAAgB,CAAC,CAAC;AA6G/B;;;;;;;;;;GAUG;AACH,wBAAsB,OAAO,CAC3B,QAAQ,EAAE,YAAY,EAAE,EACxB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EACpB,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB,GACA,OAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC,CAmDpD"}

package/dist/concurrency.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Bounded-concurrency primitives — the single source of truth for fan-out limits.
+ *
+ * Node's single-threaded async model means parallelism over already-async work
+ * (LLM calls, tool execution) is just `Promise` concurrency. Unbounded
+ * `Promise.all` over a large collection of agent/tool work fires every task at
+ * once; this module provides a hand-rolled `pLimit`-style semaphore so at most N
+ * run concurrently, with no new dependency.
+ *
+ * Two ordering contracts are exposed:
+ * - {@link createLimiter} preserves COMPLETION semantics — `run(fn)` resolves
+ *   when `fn` resolves, and callers compose ordering themselves.
+ * - {@link mapLimit} preserves INPUT order — results map back to input position
+ *   regardless of completion order.
+ */
+/** Available logical parallelism, guarded for older Node (we target >=20). */
+export declare function availableParallelism(): number;
+/**
+ * A hand-rolled `pLimit`-style semaphore. `run(fn)` schedules `fn` so at most
+ * `concurrency` are in flight at once; it resolves with `fn`'s result.
+ */
+export declare function createLimiter(concurrency: number): <T>(fn: () => Promise<T>) => Promise<T>;
+/**
+ * Map `fn` over `items` with at most `concurrency` calls in flight, returning
+ * results in INPUT order (results map back to input position regardless of
+ * completion order). `fn` is invoked with each item and its index.
+ *
+ * Mirrors `Promise.all(items.map(fn))` semantics: it rejects with the first
+ * rejection. Callers that need per-item error capture should catch inside `fn`.
+ */
+export declare function mapLimit<TItem, TResult>(items: readonly TItem[], concurrency: number, fn: (item: TItem, index: number) => Promise<TResult>): Promise<TResult[]>;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../src/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,8EAA8E;AAC9E,wBAAgB,oBAAoB,IAAI,MAAM,CAG7C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,IAc3B,CAAC,EAAE,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC,CAczD;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EACrC,KAAK,EAAE,SAAS,KAAK,EAAE,EACvB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GACnD,OAAO,CAAC,OAAO,EAAE,CAAC,CAGpB"}