@gajae-code/agent-core 0.3.0 → 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/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/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.3.0",
+	"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.3.0",
-		"@gajae-code/natives": "0.3.0",
-		"@gajae-code/utils": "0.3.0",
+		"@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/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