@gajae-code/agent-core 0.2.5 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-06-05
+
+### Fixed
+
+- Moved the env-driven full message content capture warning into agent-core telemetry resolution so direct `@gajae-code/agent-core` consumers receive `full_content_capture_env_active` when `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=full` is used without an explicit `captureMessageContent` override.
+
+### Changed
+
+- Clarified that telemetry `summary` content capture emits bounded real-content snippets in `pi.gen_ai.*` attributes and is not redacted or PII-free.
+
 ## [0.2.4] - 2026-06-02
 
 ### Added

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/telemetry.d.ts

@@ -211,8 +211,9 @@ export interface AgentIdentity {
     readonly name?: string;
     readonly description?: string;
 }
+export type AgentTelemetryWarningCode = "resolve_attributes_failed" | "content_serializer_failed" | "on_cost_delta_failed" | "on_chat_usage_failed" | "cost_estimator_failed" | "on_run_end_failed" | "on_span_start_failed" | "on_span_end_failed" | "normalize_agent_name_failed" | "normalize_provider_failed" | "full_content_capture_env_active" | "on_telemetry_warning_failed";
 export interface AgentTelemetryWarning {
-    readonly code: "resolve_attributes_failed" | "content_serializer_failed" | "on_cost_delta_failed" | "on_chat_usage_failed" | "cost_estimator_failed" | "on_run_end_failed" | "on_span_start_failed" | "on_span_end_failed" | "normalize_agent_name_failed" | "normalize_provider_failed" | "on_telemetry_warning_failed";
+    readonly code: AgentTelemetryWarningCode;
     readonly message: string;
     readonly error?: unknown;
 }
@@ -249,12 +250,18 @@ export interface AgentTelemetryConfig {
     /** Override the tracer name passed to `trace.getTracer`. */
     readonly tracerName?: string;
     /**
-     * Capture request/response content. `true` preserves the historical full
-     * payload capture; `"summary"` emits bounded dashboard-friendly summaries;
-     * `"full"` emits both summaries and full OTEL message payloads.
+     * Capture request/response content. Programmatic `true` preserves the
+     * historical full payload capture because code config is an explicit opt-in;
+     * `"summary"` emits bounded dashboard-friendly summaries in
+     * `pi.gen_ai.request.messages`, `pi.gen_ai.response.text`, and related
+     * `pi.gen_ai.*` attributes. Summary mode is not redacted or PII-free: text is
+     * truncated to bounded snippets, not removed. `"full"` emits both summaries
+     * and full OTEL message payloads.
      *
      * Defaults to the value of the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`
-     * env var (`true`/`1`/`yes` => `"full"`, `"summary"` => `"summary"`).
+     * env var (`true`/`1`/`yes` => `"summary"`, `"summary"` => `"summary"`,
+     * `"full"` => `"full"`). Env-driven `"full"` capture emits a
+     * `full_content_capture_env_active` telemetry warning once per process.
      */
     readonly captureMessageContent?: TelemetryContentCapture;
     /** Extra attributes merged onto every emitted span. */
@@ -335,6 +342,7 @@ export interface AgentTelemetry {
 }
 /** Lazily resolve the {@link AgentTelemetry} handle. Returns `undefined` when disabled. */
 export declare function resolveTelemetry(config: AgentTelemetryConfig | undefined, sessionId: string | undefined): AgentTelemetry | undefined;
+export declare function resetContentCaptureEnvCacheForTest(): void;
 export declare function recordTelemetryWarning(telemetry: AgentTelemetry | undefined, warning: AgentTelemetryWarning): void;
 /**
  * Start the outer `invoke_agent` span that wraps a full `runLoop` invocation.

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.1",
 	"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.1",
+		"@gajae-code/natives": "0.3.1",
+		"@gajae-code/utils": "0.3.1",
 		"@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/telemetry.ts

@@ -55,6 +55,9 @@ export const DEFAULT_TRACER_NAME = "@gajae-code/agent-core";
 
 /** Env var matching the OTEL semconv content-capture toggle. */
 const CONTENT_CAPTURE_ENV = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT";
+const FULL_CONTENT_CAPTURE_ENV_WARNING =
+	`${CONTENT_CAPTURE_ENV}=full enables full GenAI message content capture. ` +
+	`Use ${CONTENT_CAPTURE_ENV}=summary for bounded telemetry summaries.`;
 
 const MAX_TELEMETRY_ARRAY_ITEMS = 64;
 const MAX_TELEMETRY_MESSAGE_COUNT = 16;
@@ -271,19 +274,22 @@ export interface AgentIdentity {
 	readonly description?: string;
 }
 
+export type AgentTelemetryWarningCode =
+	| "resolve_attributes_failed"
+	| "content_serializer_failed"
+	| "on_cost_delta_failed"
+	| "on_chat_usage_failed"
+	| "cost_estimator_failed"
+	| "on_run_end_failed"
+	| "on_span_start_failed"
+	| "on_span_end_failed"
+	| "normalize_agent_name_failed"
+	| "normalize_provider_failed"
+	| "full_content_capture_env_active"
+	| "on_telemetry_warning_failed";
+
 export interface AgentTelemetryWarning {
-	readonly code:
-		| "resolve_attributes_failed"
-		| "content_serializer_failed"
-		| "on_cost_delta_failed"
-		| "on_chat_usage_failed"
-		| "cost_estimator_failed"
-		| "on_run_end_failed"
-		| "on_span_start_failed"
-		| "on_span_end_failed"
-		| "normalize_agent_name_failed"
-		| "normalize_provider_failed"
-		| "on_telemetry_warning_failed";
+	readonly code: AgentTelemetryWarningCode;
 	readonly message: string;
 	readonly error?: unknown;
 }
@@ -322,12 +328,18 @@ export interface AgentTelemetryConfig {
 	/** Override the tracer name passed to `trace.getTracer`. */
 	readonly tracerName?: string;
 	/**
-	 * Capture request/response content. `true` preserves the historical full
-	 * payload capture; `"summary"` emits bounded dashboard-friendly summaries;
-	 * `"full"` emits both summaries and full OTEL message payloads.
+	 * Capture request/response content. Programmatic `true` preserves the
+	 * historical full payload capture because code config is an explicit opt-in;
+	 * `"summary"` emits bounded dashboard-friendly summaries in
+	 * `pi.gen_ai.request.messages`, `pi.gen_ai.response.text`, and related
+	 * `pi.gen_ai.*` attributes. Summary mode is not redacted or PII-free: text is
+	 * truncated to bounded snippets, not removed. `"full"` emits both summaries
+	 * and full OTEL message payloads.
 	 *
 	 * Defaults to the value of the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`
-	 * env var (`true`/`1`/`yes` => `"full"`, `"summary"` => `"summary"`).
+	 * env var (`true`/`1`/`yes` => `"summary"`, `"summary"` => `"summary"`,
+	 * `"full"` => `"full"`). Env-driven `"full"` capture emits a
+	 * `full_content_capture_env_active` telemetry warning once per process.
 	 */
 	readonly captureMessageContent?: TelemetryContentCapture;
 	/** Extra attributes merged onto every emitted span. */
@@ -415,8 +427,9 @@ export function resolveTelemetry(
 ): AgentTelemetry | undefined {
 	if (!config) return undefined;
 	const tracer = config.tracer ?? trace.getTracer(config.tracerName ?? DEFAULT_TRACER_NAME);
+	const contentCaptureFromEnv = config.captureMessageContent === undefined;
 	const contentCapture = resolveContentCapture(config.captureMessageContent);
-	return {
+	const telemetry = {
 		config,
 		tracer,
 		captureMessageContent: contentCapture === "full",
@@ -425,9 +438,12 @@ export function resolveTelemetry(
 		agent: config.agent,
 		collector: new AgentRunCollector(),
 	};
+	warnIfEnvFullContentCaptureActive(telemetry, contentCaptureFromEnv);
+	return telemetry;
 }
 
 let contentCaptureEnvCache: ResolvedTelemetryContentCapture | undefined;
+let hasWarnedFullContentCaptureEnv = false;
 function readContentCaptureEnv(): ResolvedTelemetryContentCapture {
 	if (contentCaptureEnvCache !== undefined) return contentCaptureEnvCache;
 	const raw = process.env[CONTENT_CAPTURE_ENV];
@@ -436,15 +452,21 @@ function readContentCaptureEnv(): ResolvedTelemetryContentCapture {
 		return "none";
 	}
 	const normalized = raw.trim().toLowerCase();
-	if (normalized === "summary") {
+	if (normalized === "full") {
+		contentCaptureEnvCache = "full";
+	} else if (normalized === "summary" || normalized === "true" || normalized === "1" || normalized === "yes") {
 		contentCaptureEnvCache = "summary";
 	} else {
-		contentCaptureEnvCache =
-			normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "full" ? "full" : "none";
+		contentCaptureEnvCache = "none";
 	}
 	return contentCaptureEnvCache;
 }
 
+export function resetContentCaptureEnvCacheForTest(): void {
+	contentCaptureEnvCache = undefined;
+	hasWarnedFullContentCaptureEnv = false;
+}
+
 function resolveContentCapture(value: TelemetryContentCapture | undefined): ResolvedTelemetryContentCapture {
 	const capture = value ?? readContentCaptureEnv();
 	if (capture === true || capture === "full") return "full";
@@ -452,6 +474,15 @@ function resolveContentCapture(value: TelemetryContentCapture | undefined): Reso
 	return "none";
 }
 
+function warnIfEnvFullContentCaptureActive(telemetry: AgentTelemetry, contentCaptureFromEnv: boolean): void {
+	if (!contentCaptureFromEnv || telemetry.contentCapture !== "full" || hasWarnedFullContentCaptureEnv) return;
+	hasWarnedFullContentCaptureEnv = true;
+	emitTelemetryWarning(telemetry, {
+		code: "full_content_capture_env_active",
+		message: FULL_CONTENT_CAPTURE_ENV_WARNING,
+	});
+}
+
 /**
  * Start a span with the standard attribute envelope (provider, operation,
  * conversation, agent identity, user-supplied extras) pre-applied. Returns

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;