@namzu/sdk 62.13.0 → 62.14.0

package/src/telemetry/genai.ts

@@ -0,0 +1,202 @@
+import type { Attributes } from '@opentelemetry/api'
+import { isProviderRequestError } from '../provider/errors.js'
+import type { TokenUsage } from '../types/common/index.js'
+import { GENAI } from './attributes.js'
+
+/**
+ * The OpenTelemetry semantic conventions for generative AI, as far as the
+ * spans of this kernel follow them.
+ *
+ * The convention is still marked "Development", so its names can change
+ * between releases. What the kernel emits is therefore pinned to ONE released
+ * version, and says so: the instrumentation scope carries the schema URL of
+ * that version. The text of the convention was published in the
+ * `semantic-conventions` repository up to and including v1.41.1; later
+ * releases only point to a new repository. Moving the pin means reading the
+ * new text, changing {@link GENAI_SEMCONV_VERSION} and the table in
+ * `docs/sdk/telemetry-genai.md` together; a test fails when an attribute name
+ * is emitted that is not in {@link GENAI_SEMCONV_ATTRIBUTES}.
+ *
+ * Everything here is additive: the kernel's own names (`namzu.*`, and the
+ * `gen_ai.*` names it already wrote) are untouched. One process-wide switch
+ * turns the new names off for a backend that bills by attribute.
+ */
+export const GENAI_SEMCONV_VERSION = '1.41.1'
+
+/** Schema URL of the pinned version; set on the tracer's instrumentation scope. */
+export const GENAI_SEMCONV_SCHEMA_URL = `https://opentelemetry.io/schemas/${GENAI_SEMCONV_VERSION}`
+
+/** `gen_ai.operation.name` values this kernel uses; all three are in the pinned convention's list. */
+export const GENAI_OPERATION = {
+	CHAT: 'chat',
+	EXECUTE_TOOL: 'execute_tool',
+	INVOKE_AGENT: 'invoke_agent',
+} as const
+
+/** The convention's name for the error class of a failed operation (stable). */
+export const ERROR_TYPE = 'error.type'
+
+/** The convention's fallback `error.type` value. */
+export const ERROR_TYPE_OTHER = '_OTHER'
+
+/**
+ * Every attribute name the pinned convention version defines for the three
+ * span kinds this kernel emits (inference, execute tool, invoke agent) that
+ * the kernel may write, whether the kernel's own earlier code or the additions
+ * wrote it. A span's `gen_ai.*` / `error.type` keys must all be in here, with
+ * the one exception named in {@link GENAI_NON_CONVENTION_NAMES}.
+ */
+export const GENAI_SEMCONV_ATTRIBUTES: readonly string[] = [
+	GENAI.OPERATION_NAME,
+	GENAI.PROVIDER_NAME,
+	ERROR_TYPE,
+	GENAI.CONVERSATION_ID,
+	GENAI.AGENT_NAME,
+	GENAI.AGENT_ID,
+	GENAI.REQUEST_MODEL,
+	GENAI.REQUEST_STREAM,
+	GENAI.REQUEST_TEMPERATURE,
+	GENAI.REQUEST_MAX_TOKENS,
+	GENAI.RESPONSE_MODEL,
+	GENAI.RESPONSE_ID,
+	GENAI.RESPONSE_FINISH_REASONS,
+	GENAI.USAGE_INPUT_TOKENS,
+	GENAI.USAGE_OUTPUT_TOKENS,
+	GENAI.USAGE_CACHE_READ_INPUT_TOKENS,
+	GENAI.USAGE_CACHE_CREATION_INPUT_TOKENS,
+	GENAI.USAGE_REASONING_OUTPUT_TOKENS,
+	GENAI.TOOL_NAME,
+	GENAI.TOOL_CALL_ID,
+	GENAI.TOOL_TYPE,
+]
+
+/**
+ * `gen_ai.*` names the kernel writes that are NOT in the pinned convention.
+ * `gen_ai.system` is still in the 1.41.1 registry but deprecated, replaced by
+ * `gen_ai.provider.name`; the kernel emits it deliberately and
+ * it stays because it is existing output that nothing may remove.
+ */
+export const GENAI_NON_CONVENTION_NAMES: readonly string[] = [GENAI.SYSTEM]
+
+let enabled = true
+
+/**
+ * Turn the convention's attribute names (and the schema URL) on or off for
+ * every span the kernel starts from now on. On by default. `@namzu/telemetry`
+ * calls this from `TelemetryConfig.genAiAttributes`; a host that does not use
+ * that package can call it directly.
+ */
+export function setGenAiConventions(on: boolean): void {
+	enabled = on
+}
+
+export function genAiConventionsEnabled(): boolean {
+	return enabled
+}
+
+/**
+ * The value for `gen_ai.provider.name`, which the convention requires on every
+ * span that carries it.
+ *
+ * The convention (1.41.1) says: "If one of them applies, then the respective
+ * value MUST be used; otherwise, a custom value MAY be used." and states no
+ * further rule on the form of a custom value. So:
+ *
+ * - a listed value only when our provider IS that vendor's own API (the
+ *   cases below; `google` is `gcp.gen_ai`, "Any Google generative AI
+ *   endpoint", since our id does not say which one);
+ * - otherwise our own provider id, lower case, as the custom value. A gateway
+ *   that forwards to several vendors, a local runner and a custom HTTP
+ *   endpoint are never mapped to a vendor they are not.
+ *
+ * `undefined` only when there is no provider id at all.
+ */
+export function genAiProviderName(providerId: string | undefined): string | undefined {
+	switch (providerId) {
+		case 'anthropic':
+			return 'anthropic'
+		case 'bedrock':
+			return 'aws.bedrock'
+		case 'deepseek':
+			return 'deepseek'
+		case 'google':
+			return 'gcp.gen_ai'
+		case 'openai':
+		case 'codex':
+			return 'openai'
+		default: {
+			const own = providerId?.trim().toLowerCase()
+			return own ? own : undefined
+		}
+	}
+}
+
+/**
+ * A low-cardinality class for a failure, for `error.type`: the provider
+ * error kind for a classified provider failure, the error's own class name
+ * for an exception, `_OTHER` for anything else (a thrown string, a plain
+ * `Error`).
+ */
+export function genAiErrorType(err: unknown): string {
+	if (isProviderRequestError(err)) return err.kind
+	if (err instanceof Error) {
+		const name = err.name
+		return name && name !== 'Error' ? name : ERROR_TYPE_OTHER
+	}
+	return ERROR_TYPE_OTHER
+}
+
+/** Added when a turn (an agent run, a sub-agent included) starts. */
+export function agentRunAttributes(providerId: string | undefined): Attributes {
+	if (!enabled) return {}
+	const provider = genAiProviderName(providerId)
+	return {
+		[GENAI.OPERATION_NAME]: GENAI_OPERATION.INVOKE_AGENT,
+		...(provider !== undefined ? { [GENAI.PROVIDER_NAME]: provider } : {}),
+	}
+}
+
+/** Added when a model call starts. Every model call is streamed. */
+export function chatStartAttributes(providerId: string | undefined): Attributes {
+	if (!enabled) return {}
+	const provider = genAiProviderName(providerId)
+	return {
+		...(provider !== undefined ? { [GENAI.PROVIDER_NAME]: provider } : {}),
+		[GENAI.REQUEST_STREAM]: true,
+	}
+}
+
+/**
+ * Added when a model call answers. A count is written only when the driver
+ * reported a positive one: the record cannot tell "none" from "not
+ * reported", so a zero is left out rather than stated.
+ */
+export function chatUsageAttributes(usage: TokenUsage): Attributes {
+	if (!enabled) return {}
+	return {
+		...(usage.cachedTokens > 0
+			? { [GENAI.USAGE_CACHE_READ_INPUT_TOKENS]: usage.cachedTokens }
+			: {}),
+		...(usage.cacheWriteTokens > 0
+			? { [GENAI.USAGE_CACHE_CREATION_INPUT_TOKENS]: usage.cacheWriteTokens }
+			: {}),
+		...(usage.reasoningTokens !== undefined && usage.reasoningTokens > 0
+			? { [GENAI.USAGE_REASONING_OUTPUT_TOKENS]: usage.reasoningTokens }
+			: {}),
+	}
+}
+
+/** Added when a tool call starts. */
+export function toolCallAttributes(): Attributes {
+	if (!enabled) return {}
+	return { [GENAI.OPERATION_NAME]: GENAI_OPERATION.EXECUTE_TOOL }
+}
+
+/** The `error.type` of a tool call the kernel refused (not available, not allowed, plan mode); a custom low-cardinality value, which the convention allows. */
+export const PERMISSION_DENIED = 'permission_denied'
+
+/** Added to a span whose operation ended in an error. */
+export function errorTypeAttributes(errorType: string): Attributes {
+	if (!enabled) return {}
+	return { [ERROR_TYPE]: errorType }
+}

package/src/telemetry/runtime-accessors.ts

@@ -9,9 +9,19 @@
 // discarded — standard OTEL library behavior.
 
 import { type SpanContext, type Tracer, context, trace } from '@opentelemetry/api'
+import { GENAI_SEMCONV_SCHEMA_URL, genAiConventionsEnabled } from './genai.js'
 
+/**
+ * The kernel's tracer. While the GenAI convention names are on, its
+ * instrumentation scope carries the schema URL of the pinned convention
+ * version, which is how the convention says a producer states the version.
+ */
 export function getTracer(): Tracer {
-	return trace.getTracer('namzu')
+	return genAiConventionsEnabled()
+		? trace
+				.getTracerProvider()
+				.getTracer('namzu', undefined, { schemaUrl: GENAI_SEMCONV_SCHEMA_URL })
+		: trace.getTracer('namzu')
 }
 
 /**

package/src/toolsets/manager.ts

@@ -6,6 +6,13 @@ import { assertToolName, describeWithOutput, toolDiscoveryHint } from '../regist
 import { renderToolSchema, toolWireSchema } from '../registry/tool/schema.js'
 import { ToolResultHalted, screenToolResult } from '../registry/tool/screen.js'
 import { GENAI, NAMZU, toolSpanName } from '../telemetry/attributes.js'
+import {
+	ERROR_TYPE_OTHER,
+	PERMISSION_DENIED,
+	errorTypeAttributes,
+	genAiErrorType,
+	toolCallAttributes,
+} from '../telemetry/genai.js'
 import { recordToolCall } from '../telemetry/metrics.js'
 import { getTracer } from '../telemetry/runtime-accessors.js'
 import { failureFactsFromError } from '../tools/failure-facts.js'
@@ -804,6 +811,8 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 					[GENAI.TOOL_TYPE]: 'function',
 					...(context.toolUseId !== undefined ? { [GENAI.TOOL_CALL_ID]: context.toolUseId } : {}),
 					...toolSpanIdentity(context),
+					...toolCallAttributes(),
+					...errorTypeAttributes(genAiErrorType(err)),
 					[NAMZU.TOOL_SUCCESS]: false,
 					[NAMZU.TOOL_ERROR]: toErrorMessage(err),
 				})
@@ -841,6 +850,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 					[GENAI.TOOL_TYPE]: 'function',
 					...(context.toolUseId !== undefined ? { [GENAI.TOOL_CALL_ID]: context.toolUseId } : {}),
 					...toolSpanIdentity(context),
+					...toolCallAttributes(),
 				})
 
 				// The permitted `this.getAvailability` substitution: derived,
@@ -852,6 +862,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 					span.setAttributes({
 						[NAMZU.TOOL_SUCCESS]: false,
 						[NAMZU.TOOL_ERROR]: msg,
+						...errorTypeAttributes(ERROR_TYPE_OTHER),
 					})
 					span.setStatus({ code: SpanStatusCode.ERROR, message: msg })
 					return {
@@ -871,6 +882,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 					span.setAttributes({
 						[NAMZU.TOOL_SUCCESS]: false,
 						[NAMZU.TOOL_ERROR]: msg,
+						...errorTypeAttributes(PERMISSION_DENIED),
 					})
 					span.setStatus({ code: SpanStatusCode.ERROR, message: msg })
 					return {
@@ -889,6 +901,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 						span.setAttributes({
 							[NAMZU.TOOL_SUCCESS]: false,
 							[NAMZU.TOOL_ERROR]: msg,
+							...errorTypeAttributes(PERMISSION_DENIED),
 						})
 						span.setStatus({ code: SpanStatusCode.ERROR, message: msg })
 						return {
@@ -932,6 +945,13 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 					)
 					if (!result.success && result.error) {
 						span.setAttribute(NAMZU.TOOL_ERROR, result.error)
+						span.setAttributes(
+							errorTypeAttributes(
+								'permissionDenied' in result && result.permissionDenied
+									? PERMISSION_DENIED
+									: ERROR_TYPE_OTHER,
+							),
+						)
 						span.setStatus({
 							code: SpanStatusCode.ERROR,
 							message: result.error,
@@ -946,6 +966,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 						span.setAttributes({
 							[NAMZU.TOOL_SUCCESS]: false,
 							[NAMZU.TOOL_ERROR]: err.message,
+							...errorTypeAttributes(genAiErrorType(err)),
 						})
 						span.setStatus({
 							code: SpanStatusCode.ERROR,
@@ -962,6 +983,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 					span.setAttributes({
 						[NAMZU.TOOL_SUCCESS]: false,
 						[NAMZU.TOOL_ERROR]: errorMessage,
+						...errorTypeAttributes(genAiErrorType(err)),
 					})
 					span.setStatus({
 						code: SpanStatusCode.ERROR,

package/src/types/acp/index.ts

@@ -38,7 +38,27 @@ export interface AcpInitializeParams extends AcpClientCapabilities {
 	readonly clientInfo?: { readonly name?: string; readonly version?: string }
 }
 
+/**
+ * What a host says about the engine it runs, in `initialize`. A reader that
+ * does not know this object ignores it.
+ */
+export interface AcpKernelFacts {
+	/** The engine's own version (this package's). */
+	readonly engine: string
+	/** The data epoch of the on-disk formats this engine writes. */
+	readonly dataEpoch: number
+	/** The version of the application that hosts the engine, when that application says one. */
+	readonly commandLine?: string
+	/** The contract number an installed client application checks, when the host was started for one. */
+	readonly desktopContract?: number
+}
+
+/** The two facts a host application adds to `AcpKernelFacts`; the engine states the rest itself. */
+export type AcpHostKernelFacts = Pick<AcpKernelFacts, 'commandLine' | 'desktopContract'>
+
 export interface AcpInitializeResult {
+	/** The engine and data facts a client may use to decide whether this host is safe for it. */
+	readonly kernel?: AcpKernelFacts
 	/** True only when the host gateway opts into inline user attachment delivery. */
 	readonly promptAttachments?: boolean
 	/** True only when this host applies captured effort and review settings per prompt. */