@gajae-code/agent-core 0.10.2 → 0.11.0

package/CHANGELOG.md

@@ -8,6 +8,10 @@
 
 - Extended the gpt-5.6 `Request blocked (code=invalid_prompt)` fix to the compaction paths that bypass the streaming transport. Remote OpenAI compaction (`/responses/compact`, `compaction.remoteEnabled` default on — the "remote compact task" in openai/codex#32028) built its native `input` from reasoning signatures, verbatim history items, and message/tool text without neutralizing leaked Harmony control-token markers (e.g. `<|channel|>analysis`), so gpt-5.6 rejected the compaction request and, on retry, could escalate to account-level blocking. `requestOpenAiRemoteCompaction` now neutralizes reserved control tokens across the whole outgoing `input`, and the generic `requestRemoteCompaction` prompt/systemPrompt are neutralized too. Local summarization was already covered by the streaming-transport request-boundary fix.
 
+### Changed
+
+- `AgentLoopConfig.maintainContext` now receives a required cancellation-aware lifecycle (`signal`, `awaitEventDrain(invocationSignal)`). Agent loops compose the run and maintenance-invocation signals and pass that single signal to EventStream's FIFO consumer-drain barrier, so cancellation removes the pending drain at its owner instead of racing an orphaned wait.
+
 ## [0.10.0] - 2026-07-12
 
 ### Fixed

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

@@ -5,11 +5,19 @@
 import { type Context, EventStream } from "@gajae-code/ai";
 import { type AgentRunCoverage, type AgentRunSummary } from "./run-collector";
 import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types";
+/** Sentinel returned by the abort race in `streamAssistantResponse`. */
+/**
+ * Defensive caps for a provisional managed attempt. These are intentionally
+ * well above ordinary streamed responses; they only bound memory when an
+ * upstream emits an unbounded event stream before the attempt can commit.
+ */
+export declare const MANAGED_ATTEMPT_MAX_STAGED_EVENTS = 10000;
+export declare const MANAGED_ATTEMPT_MAX_STAGED_BYTES: number;
 /**
  * Start an agent loop with a new prompt message.
  * The prompt is added to the context and events are emitted for it.
  */
-export declare function agentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
+export declare function agentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn, emitManagedAgentStart?: boolean): EventStream<AgentEvent, AgentMessage[]>;
 /**
  * Continue an agent loop from the current context without adding a new message.
  * Used for retries - context already has user message or tool results.
@@ -18,7 +26,7 @@ export declare function agentLoop(prompts: AgentMessage[], context: AgentContext
  * via `convertToLlm`. If it doesn't, the LLM provider will reject the request.
  * This cannot be validated here since `convertToLlm` is only called once per turn.
  */
-export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
+export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn, emitManagedAgentStart?: boolean): EventStream<AgentEvent, AgentMessage[]>;
 /**
  * Detailed-result handle returned by {@link agentLoopDetailed}. Adds the
  * run-level telemetry/coverage rollup to the existing `AgentMessage[]`

package/dist/types/agent.d.ts

@@ -4,13 +4,16 @@
 import { type AssistantMessage, type AssistantMessageEvent, type CursorExecHandlers, type CursorToolResultHandler, type Effort, type ImageContent, type Message, type Model, type ProviderSessionState, type ServiceTier, type SimpleStreamOptions, type ThinkingBudgets, type ToolChoice } from "@gajae-code/ai";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { HarmonyAuditEvent } from "./harmony-leak";
-import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, StreamFn, ToolCallContext } from "./types";
+import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, ManagedLogicalRunId, RunTerminalRequest, StreamFn, ToolCallContext } from "./types";
 /**
  * Whether persisted history ends at a point where a new model turn can resume.
  * Assistant-ended histories require an in-memory queued message and are handled
  * separately by `Agent.continue()`.
  */
 export declare function canContinuePersistedHistory(messages: readonly AgentMessage[]): boolean;
+export declare class ManagedCursorInvariantError extends Error {
+    constructor(message?: string);
+}
 export declare class AgentBusyError extends Error {
     constructor(message?: string);
 }
@@ -170,6 +173,16 @@ export interface AgentOptions {
 }
 export interface AgentPromptOptions {
     toolChoice?: ToolChoice;
+    /** Disable transport replay; fallback accounting is owned by the caller. */
+    fallbackManaged?: boolean;
+    /** Called synchronously after this invocation claims the agent run, before asynchronous provider work. */
+    onRunAccepted?: () => void;
+    /** Called once immediately before every managed upstream request. */
+    nextFallbackAttempt?: AgentLoopConfig["nextFallbackAttempt"];
+    /** Called after a managed upstream request is accepted and committed. */
+    onManagedAttemptAccepted?: AgentLoopConfig["onManagedAttemptAccepted"];
+    /** Receives a discarded managed attempt without exposing assistant lifecycle events. */
+    onManagedAttemptOutcome?: AgentLoopConfig["onManagedAttemptOutcome"];
 }
 export declare class Agent {
     #private;
@@ -307,6 +320,7 @@ export declare class Agent {
     setAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
     setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void;
     setShouldPause(fn: AgentLoopConfig["shouldPause"] | undefined): void;
+    setMaintainContext(fn: AgentLoopConfig["maintainContext"] | undefined): void;
     emitExternalEvent(event: AgentEvent): void;
     createExternalEventEmitterForCurrentRun(): ((event: AgentEvent) => void) | undefined;
     setSystemPrompt(v: string[]): void;
@@ -391,6 +405,24 @@ export declare class Agent {
      */
     forceAbort(reason?: string): boolean;
     waitForIdle(): Promise<void>;
+    /** The active per-attempt run identifier. */
+    get activeRunId(): number | undefined;
+    /**
+     * Stable identifier for the active managed logical run, shared by every retry
+     * attempt. Pass this value to requestRunTerminal(); never retain activeRunId
+     * for managed terminal completion.
+     */
+    get currentManagedLogicalRunId(): ManagedLogicalRunId | undefined;
+    /**
+     * Request terminal completion through the single logical-run keyed finalizer.
+     *
+     * For managed runs, logicalRunId must be currentManagedLogicalRunId from any
+     * attempt in the retry chain. Non-managed runs use their activeRunId. Terminal
+     * requests with messages emit a committed message_start/message_end lifecycle
+     * for each diagnostic before agent_end. Requests without messages (such as
+     * cancellation) emit only agent_end.
+     */
+    requestRunTerminal(logicalRunId: ManagedLogicalRunId, request: RunTerminalRequest): boolean;
     reset(): void;
     /** Send a prompt with an AgentMessage */
     prompt(message: AgentMessage | AgentMessage[], options?: AgentPromptOptions): Promise<void>;
@@ -399,5 +431,5 @@ export declare class Agent {
     /**
      * Continue from current context (used for retries and resuming queued messages).
      */
-    continue(): Promise<void>;
+    continue(options?: AgentPromptOptions): Promise<void>;
 }

package/dist/types/compaction/entries.d.ts

@@ -100,9 +100,19 @@ export interface ModeChangeEntry extends SessionEntryBase {
     /** Optional mode-specific data (e.g. plan file path) */
     data?: Record<string, unknown>;
 }
+export interface ConfiguredModelChainEntry extends SessionEntryBase {
+    type: "configured_model_chain";
+    role: string;
+    entries: readonly string[];
+    origin: string;
+    identity?: string;
+    explicitHead: boolean;
+    /** Whether this entry removes the configured chain for its role. */
+    cleared?: boolean;
+}
 export interface CustomCompactionSessionEntries {
 }
-export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | ServiceTierChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | TtsrInjectionEntry | MCPToolSelectionEntry | SessionInitEntry | ModeChangeEntry | CustomCompactionSessionEntries[keyof CustomCompactionSessionEntries];
+export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | ServiceTierChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | TtsrInjectionEntry | MCPToolSelectionEntry | SessionInitEntry | ModeChangeEntry | ConfiguredModelChainEntry | CustomCompactionSessionEntries[keyof CustomCompactionSessionEntries];
 export interface ReadonlySessionManager {
     getBranch(leafId?: string | null): SessionEntry[];
     getEntry(id: string): SessionEntry | undefined;

package/dist/types/types.d.ts

@@ -5,11 +5,76 @@ import type { AgentRunCoverage, AgentRunSummary } from "./run-collector";
 import type { AgentTelemetryConfig } from "./telemetry";
 /** Stream function - can return sync or Promise for async config lookup */
 export type StreamFn = (...args: Parameters<typeof streamSimple>) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
+/** Stable identifier for a managed logical run, shared by all of its retry attempts. */
+export type ManagedLogicalRunId = number;
+/** Terminal completion requested for a logical run. */
+export interface RunTerminalRequest {
+    stopReason: "cancelled" | "error" | "exhausted";
+    messages?: AgentMessage[];
+}
+/**
+ * Ownership token supplied when Agent invokes a retry continuation.
+ *
+ * A continuation MUST verify `isCurrent()` immediately before starting a
+ * follow-up invocation and abandon the retry when it returns false. The token
+ * becomes invalid when its originating run is force-aborted or superseded.
+ * Coding-agent retry continuations must accept this argument and must not call
+ * `agent.continue()` after ownership has been lost.
+ */
+export interface ManagedAttemptContinuationOwnership {
+    /** Per-attempt run-loop id; use only for attempt-local ownership checks. */
+    readonly runId: number;
+    /** Stable managed logical-run id; use for all terminal completion requests. */
+    readonly logicalRunId: ManagedLogicalRunId;
+    readonly generation: number;
+    isCurrent(): boolean;
+}
+/** Runs after a discarded attempt is idle, only while its ownership token remains current. */
+export type ManagedAttemptContinuation = (ownership: ManagedAttemptContinuationOwnership) => void | Promise<void>;
+/** Decision returned by managed fallback policy for one provisional attempt. */
+export type ManagedAttemptDecision = {
+    type: "retry";
+    continuation: ManagedAttemptContinuation;
+} | {
+    type: "terminal";
+    terminal: RunTerminalRequest;
+};
+/** Structured result for one managed upstream invocation. */
+export type ManagedAttemptOutcome = {
+    type: "retryable_discarded";
+    failure: {
+        message: AssistantMessage;
+        /** Exact provider transport facts, including retry headers, for fallback policy. */
+        transportFailure?: import("@gajae-code/ai").TransportFailureFacts;
+    };
+} | {
+    type: "run_terminal";
+    reason: "cancelled" | "error" | "exhausted";
+};
+export type ManagedAttemptOutcomeHandler = (outcome: ManagedAttemptOutcome) => ManagedAttemptDecision | Promise<ManagedAttemptDecision>;
+/**
+ * Outcome of a cooperative mid-run context-maintenance checkpoint (see
+ * {@link AgentLoopConfig.maintainContext}). Any value other than "not-needed"
+ * means the checkpoint mutated (or attempted to mutate) durable context, so the
+ * loop ends the current run without the lossy `agent_end` finalization and the
+ * maintenance owner resumes the run on the rewritten context.
+ */
+export type MidRunMaintenanceOutcome = "not-needed" | "pruned" | "compacted" | "promoted" | "failed" | "aborted";
 /**
  * Configuration for the agent loop.
  */
 export interface AgentLoopConfig extends SimpleStreamOptions {
     model: Model;
+    /**
+     * Supplies a fresh opaque token at each concrete managed transport invocation.
+     * The callback runs at the stream boundary so controller accounting matches
+     * upstream request count, including multi-step tool turns.
+     */
+    nextFallbackAttempt?: (model: Model) => SimpleStreamOptions["fallbackAttempt"];
+    /** Called after a managed upstream request is accepted and committed. */
+    onManagedAttemptAccepted?: () => void | Promise<void>;
+    /** Receives a managed invocation outcome without publishing provisional lifecycle events. */
+    onManagedAttemptOutcome?: ManagedAttemptOutcomeHandler;
     /**
      * When to interrupt tool execution for steering messages.
      * - "immediate" = check after each tool call (default)
@@ -129,6 +194,29 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Use this when tool availability or the system prompt can change mid-turn.
      */
     syncContextBeforeModelCall?: (context: AgentContext) => void | Promise<void>;
+    /**
+     * Cooperative mid-run context-maintenance checkpoint.
+     *
+     * Invoked at the top of every loop iteration AFTER pending tool-result /
+     * steering messages have been materialized into durable context and BEFORE
+     * {@link syncContextBeforeModelCall} and the model call. This is the only
+     * boundary where the full unsent context (tool results + dequeued steering)
+     * is already durable, so a long uninterrupted tool loop can be bounded here
+     * before it grows past the provider window.
+     *
+     * The callback owns the maintenance decision (prune / compact / promote) and
+     * receives the minimal cancellation-aware lifecycle: `signal` is the
+     * non-optional loop signal, and `awaitEventDrain(invocationSignal)` waits for
+     * prior event consumer bodies with loop and invocation cancellation composed.
+     * Any outcome other than "not-needed" ends the current run with
+     * `agent_end.stopReason === "maintenance"` (NOT the lossy pause / completed
+     * finalization); the callback's continuation owner resumes the run on the
+     * rewritten context.
+     */
+    maintainContext?: (context: AgentContext, lifecycle: {
+        signal: AbortSignal;
+        awaitEventDrain: (invocationSignal: AbortSignal) => Promise<void>;
+    }) => Promise<MidRunMaintenanceOutcome> | MidRunMaintenanceOutcome;
     /**
      * Optional transform applied to tool call arguments before execution.
      * Use for deobfuscating secrets or rewriting arguments.
@@ -388,8 +476,10 @@ export type AgentEvent = {
 } | {
     type: "agent_end";
     messages: AgentMessage[];
-    /** Indicates whether the loop ended normally or suspended at a pause checkpoint. */
-    stopReason?: "completed" | "paused";
+    /** Indicates whether the loop ended normally, suspended, cancelled, or entered maintenance. */
+    stopReason?: "completed" | "paused" | "cancelled" | "maintenance";
+    /** Present iff `stopReason === "maintenance"`; the maintenance outcome. */
+    maintenanceOutcome?: MidRunMaintenanceOutcome;
     /** Present iff `AgentTelemetryConfig` was supplied on this run. */
     telemetry?: AgentRunSummary;
     coverage?: AgentRunCoverage;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.10.2",
+	"version": "0.11.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -32,9 +32,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/ai": "0.10.2",
-		"@gajae-code/natives": "0.10.2",
-		"@gajae-code/utils": "0.10.2",
+		"@gajae-code/ai": "0.11.0",
+		"@gajae-code/natives": "0.11.0",
+		"@gajae-code/utils": "0.11.0",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {