@gajae-code/agent-core 0.2.5 → 0.3.0

package/dist/types/agent.d.ts

@@ -34,6 +34,8 @@ export interface AgentOptions {
      * - "wait": defer steering until the current turn completes
      */
     interruptMode?: "immediate" | "wait";
+    /** Cooperative pause checkpoint passed through to AgentLoopConfig.shouldPause. */
+    shouldPause?: AgentLoopConfig["shouldPause"];
     /**
      * API format for Kimi Code provider: "openai" or "anthropic" (default: "anthropic")
      */
@@ -289,6 +291,7 @@ export declare class Agent {
     setRawSseEventInterceptor(fn: SimpleStreamOptions["onSseEvent"] | undefined): void;
     setAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
     setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void;
+    setShouldPause(fn: AgentLoopConfig["shouldPause"] | undefined): void;
     emitExternalEvent(event: AgentEvent): void;
     createExternalEventEmitterForCurrentRun(): ((event: AgentEvent) => void) | undefined;
     setSystemPrompt(v: string[]): void;
@@ -318,6 +321,21 @@ export declare class Agent {
     clearFollowUpQueue(): void;
     clearAllQueues(): void;
     hasQueuedMessages(): boolean;
+    hasQueuedSteering(): boolean;
+    /**
+     * Snapshot the steering queue without mutating it. Used to preserve queued
+     * steering across maintenance ops (compaction/handoff) that call reset().
+     */
+    snapshotSteering(): AgentMessage[];
+    /**
+     * Restore previously snapshotted steering messages ahead of any newly
+     * queued ones. No-op for an empty snapshot.
+     */
+    restoreSteering(messages: AgentMessage[]): void;
+    /** Snapshot the follow-up queue without mutating it. */
+    snapshotFollowUp(): AgentMessage[];
+    /** Restore previously snapshotted follow-up messages ahead of any newly queued ones. */
+    restoreFollowUp(messages: AgentMessage[]): void;
     /**
      * Remove and return the last steering message from the queue (LIFO).
      * Used by dequeue keybinding.

package/dist/types/types.d.ts

@@ -103,6 +103,15 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * continues with another turn.
      */
     getFollowUpMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Cooperative pause checkpoint evaluated at safe loop boundaries.
+     *
+     * Called after completed tool execution has been emitted and before the loop
+     * polls steering/follow-up queues or schedules another assistant response.
+     * Returning true ends the current loop with `agent_end.stopReason === "paused"`
+     * without aborting any in-flight model or tool work.
+     */
+    shouldPause?: () => boolean;
     /**
      * Hook fired right before the loop would exit.
      *
@@ -375,6 +384,8 @@ export type AgentEvent = {
 } | {
     type: "agent_end";
     messages: AgentMessage[];
+    /** Indicates whether the loop ended normally or suspended at a pause checkpoint. */
+    stopReason?: "completed" | "paused";
     /** 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.2.5",
+	"version": "0.3.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -35,9 +35,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/ai": "0.2.5",
-		"@gajae-code/natives": "0.2.5",
-		"@gajae-code/utils": "0.2.5",
+		"@gajae-code/ai": "0.3.0",
+		"@gajae-code/natives": "0.3.0",
+		"@gajae-code/utils": "0.3.0",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -203,13 +203,15 @@ function buildAgentEndEvent(
 	messages: AgentMessage[],
 	telemetry: AgentTelemetry | undefined,
 	stepCount: number,
+	stopReason: "completed" | "paused" = "completed",
 ): Extract<AgentEvent, { type: "agent_end" }> {
-	if (!telemetry) return { type: "agent_end", messages };
+	const base = { type: "agent_end" as const, messages, stopReason };
+	if (!telemetry) return base;
 	const snapshot = telemetry.collector.snapshot({ stepCount });
 	if (telemetry.collector.markRunEnded()) {
 		fireOnRunEnd(telemetry, snapshot.summary, snapshot.coverage);
 	}
-	return { type: "agent_end", messages, telemetry: snapshot.summary, coverage: snapshot.coverage };
+	return { ...base, telemetry: snapshot.summary, coverage: snapshot.coverage };
 }
 
 /**
@@ -585,11 +587,26 @@ async function runLoopBody(
 
 			stream.push({ type: "turn_end", message, toolResults });
 
-			pendingMessages = steeringMessagesFromExecution ?? ((await config.getSteeringMessages?.()) || []);
+			if (steeringMessagesFromExecution && steeringMessagesFromExecution.length > 0) {
+				pendingMessages = steeringMessagesFromExecution;
+				continue;
+			}
+			pendingMessages = (await config.getSteeringMessages?.()) || [];
+			if (pendingMessages.length > 0) continue;
+			if (config.shouldPause?.()) {
+				stream.push(buildAgentEndEvent(newMessages, telemetry, stepCounter.count, "paused"));
+				stream.end(newMessages);
+				return;
+			}
 		}
 
 		// Agent would stop here. Check for follow-up messages.
 		await config.onBeforeYield?.();
+		if (config.shouldPause?.()) {
+			stream.push(buildAgentEndEvent(newMessages, telemetry, stepCounter.count, "paused"));
+			stream.end(newMessages);
+			return;
+		}
 		const followUpMessages = (await config.getFollowUpMessages?.()) || [];
 		if (followUpMessages.length > 0) {
 			// Set as pending so inner loop processes them

package/src/agent.ts

@@ -99,6 +99,8 @@ export interface AgentOptions {
 	 * - "wait": defer steering until the current turn completes
 	 */
 	interruptMode?: "immediate" | "wait";
+	/** Cooperative pause checkpoint passed through to AgentLoopConfig.shouldPause. */
+	shouldPause?: AgentLoopConfig["shouldPause"];
 
 	/**
 	 * API format for Kimi Code provider: "openai" or "anthropic" (default: "anthropic")
@@ -309,6 +311,7 @@ export class Agent {
 	#onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
 	#onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
 	#onBeforeYield?: () => Promise<void> | void;
+	#shouldPause?: AgentLoopConfig["shouldPause"];
 	#telemetry?: AgentLoopConfig["telemetry"];
 	#appendOnlyContext?: AppendOnlyContextManager;
 
@@ -371,6 +374,7 @@ export class Agent {
 		this.#getToolChoice = opts.getToolChoice;
 		this.#onAssistantMessageEvent = opts.onAssistantMessageEvent;
 		this.#onHarmonyLeak = opts.onHarmonyLeak;
+		this.#shouldPause = opts.shouldPause;
 		this.beforeToolCall = opts.beforeToolCall;
 		this.afterToolCall = opts.afterToolCall;
 		this.#telemetry = opts.telemetry;
@@ -625,6 +629,10 @@ export class Agent {
 		this.#onBeforeYield = fn;
 	}
 
+	setShouldPause(fn: AgentLoopConfig["shouldPause"] | undefined): void {
+		this.#shouldPause = fn;
+	}
+
 	emitExternalEvent(event: AgentEvent) {
 		switch (event.type) {
 			case "message_start":
@@ -859,6 +867,38 @@ export class Agent {
 		return this.#steeringQueue.length > 0 || this.#followUpQueue.length > 0;
 	}
 
+	hasQueuedSteering(): boolean {
+		return this.#steeringQueue.length > 0;
+	}
+
+	/**
+	 * Snapshot the steering queue without mutating it. Used to preserve queued
+	 * steering across maintenance ops (compaction/handoff) that call reset().
+	 */
+	snapshotSteering(): AgentMessage[] {
+		return this.#steeringQueue.slice();
+	}
+
+	/**
+	 * Restore previously snapshotted steering messages ahead of any newly
+	 * queued ones. No-op for an empty snapshot.
+	 */
+	restoreSteering(messages: AgentMessage[]): void {
+		if (messages.length === 0) return;
+		this.#steeringQueue = [...messages, ...this.#steeringQueue];
+	}
+
+	/** Snapshot the follow-up queue without mutating it. */
+	snapshotFollowUp(): AgentMessage[] {
+		return this.#followUpQueue.slice();
+	}
+
+	/** Restore previously snapshotted follow-up messages ahead of any newly queued ones. */
+	restoreFollowUp(messages: AgentMessage[]): void {
+		if (messages.length === 0) return;
+		this.#followUpQueue = [...messages, ...this.#followUpQueue];
+	}
+
 	#dequeueSteeringMessages(): AgentMessage[] {
 		if (this.#steeringMode === "one-at-a-time") {
 			if (this.#steeringQueue.length > 0) {
@@ -1196,6 +1236,10 @@ export class Agent {
 				if (this.#activeRunId !== runId) return;
 				await this.#onBeforeYield?.();
 			},
+			shouldPause: () => {
+				if (this.#activeRunId !== runId) return false;
+				return this.#shouldPause?.() === true;
+			},
 			telemetry: this.#telemetry,
 		};
 

package/src/types.ts

@@ -132,6 +132,15 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * continues with another turn.
 	 */
 	getFollowUpMessages?: () => Promise<AgentMessage[]>;
+	/**
+	 * Cooperative pause checkpoint evaluated at safe loop boundaries.
+	 *
+	 * Called after completed tool execution has been emitted and before the loop
+	 * polls steering/follow-up queues or schedules another assistant response.
+	 * Returning true ends the current loop with `agent_end.stopReason === "paused"`
+	 * without aborting any in-flight model or tool work.
+	 */
+	shouldPause?: () => boolean;
 	/**
 	 * Hook fired right before the loop would exit.
 	 *
@@ -458,6 +467,8 @@ export type AgentEvent =
 	| {
 			type: "agent_end";
 			messages: AgentMessage[];
+			/** Indicates whether the loop ended normally or suspended at a pause checkpoint. */
+			stopReason?: "completed" | "paused";
 			/** Present iff `AgentTelemetryConfig` was supplied on this run. */
 			telemetry?: AgentRunSummary;
 			coverage?: AgentRunCoverage;