@townco/agent 0.1.49 → 0.1.51

package/dist/runner/langchain/model-factory.js

@@ -74,7 +74,7 @@ export function createModelFromString(modelString) {
                 location: "global",
                 authOptions: {
                     credentials: parsedEnv,
-                    projectId: parsedEnv["project_id"],
+                    projectId: parsedEnv.project_id,
                 },
             });
         }

package/dist/runner/langchain/otel-callbacks.d.ts

@@ -0,0 +1,18 @@
+import type { CallbackHandlerMethods } from "@langchain/core/callbacks/base";
+import { type Context } from "@opentelemetry/api";
+export interface OtelCallbackOptions {
+    provider: string;
+    model: string;
+    parentContext: Context;
+}
+/**
+ * Creates OpenTelemetry callback handlers for LangChain LLM calls.
+ * These handlers instrument model invocations with OTEL spans and record token usage.
+ *
+ * @param opts - Configuration for the callbacks
+ * @param opts.provider - The LLM provider (e.g., "anthropic", "google_vertexai")
+ * @param opts.model - The model identifier
+ * @param opts.parentContext - The parent OTEL context to create child spans under
+ * @returns CallbackHandlerMethods object that can be passed to LangChain
+ */
+export declare function makeOtelCallbacks(opts: OtelCallbackOptions): CallbackHandlerMethods;

package/dist/runner/langchain/otel-callbacks.js

@@ -0,0 +1,123 @@
+import { context } from "@opentelemetry/api";
+import { telemetry } from "../../telemetry/index.js";
+/**
+ * OpenTelemetry callback handler for LangChain LLM calls.
+ * Creates spans for each LLM request to track model invocations and token usage.
+ */
+/**
+ * Map to store active spans by their LangChain run ID
+ *
+ * There's a memory leak opportunity here, but we are OK with that for now.
+ */
+const spansByRunId = new Map();
+/**
+ * Serializes LangChain messages to a JSON string for span attributes.
+ * Extracts role and content from each message.
+ */
+function serializeMessages(messages) {
+    try {
+        const flatMessages = messages.flat();
+        const serialized = flatMessages.map((msg) => ({
+            role: msg._getType(),
+            content: typeof msg.content === "string"
+                ? msg.content
+                : JSON.stringify(msg.content),
+        }));
+        return JSON.stringify(serialized);
+    }
+    catch (error) {
+        return `[Error serializing messages: ${error}]`;
+    }
+}
+/**
+ * Extracts the system prompt from LangChain messages if present.
+ */
+function extractSystemPrompt(messages) {
+    try {
+        const flatMessages = messages.flat();
+        const systemMessage = flatMessages.find((msg) => msg._getType() === "system");
+        if (systemMessage && typeof systemMessage.content === "string") {
+            return systemMessage.content;
+        }
+        return undefined;
+    }
+    catch (_error) {
+        return undefined;
+    }
+}
+/**
+ * Creates OpenTelemetry callback handlers for LangChain LLM calls.
+ * These handlers instrument model invocations with OTEL spans and record token usage.
+ *
+ * @param opts - Configuration for the callbacks
+ * @param opts.provider - The LLM provider (e.g., "anthropic", "google_vertexai")
+ * @param opts.model - The model identifier
+ * @param opts.parentContext - The parent OTEL context to create child spans under
+ * @returns CallbackHandlerMethods object that can be passed to LangChain
+ */
+export function makeOtelCallbacks(opts) {
+    return {
+        /**
+         * Called when a chat model/LLM request starts.
+         * Creates a new OTEL span for this LLM request.
+         */
+        async handleChatModelStart(_llm, messages, runId, _parentRunId, _extraParams, tags, _metadata) {
+            // Extract system prompt and serialize messages
+            const systemPrompt = extractSystemPrompt(messages);
+            const serializedMessages = serializeMessages(messages);
+            // Create span within the parent context (invocation span)
+            // Following OpenTelemetry GenAI semantic conventions:
+            // https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/
+            const span = context.with(opts.parentContext, () => telemetry.startSpan(`chat ${opts.model}`, {
+                "gen_ai.operation.name": "chat",
+                "gen_ai.provider.name": opts.provider,
+                "gen_ai.request.model": opts.model,
+                "gen_ai.input.messages": serializedMessages,
+                ...(systemPrompt
+                    ? { "gen_ai.system_instructions": systemPrompt }
+                    : {}),
+                // Custom attributes for additional context
+                "langchain.run_id": runId,
+                ...(tags && tags.length > 0
+                    ? { "langchain.tags": tags.join(",") }
+                    : {}),
+            }));
+            if (span) {
+                spansByRunId.set(runId, span);
+            }
+        },
+        /**
+         * Called when an LLM request completes successfully.
+         * Records token usage and ends the span.
+         */
+        async handleLLMEnd(output, runId) {
+            const span = spansByRunId.get(runId);
+            if (!span)
+                return;
+            // Extract token usage from LLM output
+            // The structure varies by provider but LangChain normalizes it
+            const tokenUsage = output.llmOutput?.tokenUsage;
+            if (tokenUsage) {
+                const inputTokens = tokenUsage.inputTokens ?? 0;
+                const outputTokens = tokenUsage.outputTokens ??
+                    (tokenUsage.totalTokens != null
+                        ? tokenUsage.totalTokens - inputTokens
+                        : 0);
+                telemetry.recordTokenUsage(inputTokens, outputTokens, span);
+            }
+            telemetry.endSpan(span);
+            spansByRunId.delete(runId);
+        },
+        /**
+         * Called when an LLM request fails with an error.
+         * Records the error and ends the span with error status.
+         */
+        async handleLLMError(error, runId) {
+            const span = spansByRunId.get(runId);
+            if (!span)
+                return;
+            telemetry.endSpan(span, error instanceof Error ? error : new Error(String(error)));
+            spansByRunId.delete(runId);
+        },
+    };
+}

package/dist/runner/langchain/tools/subagent.js

@@ -3,6 +3,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { Readable, Writable } from "node:stream";
 import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from "@agentclientprotocol/sdk";
+import { context, propagation, trace } from "@opentelemetry/api";
 import { z } from "zod";
 import { SUBAGENT_MODE_KEY } from "../../../acp-server/adapter.js";
 /**
@@ -235,12 +236,31 @@ async function querySubagent(agentPath, agentWorkingDirectory, query) {
                     },
                 },
             });
-            // Create a new session with subagent mode flag
+            // Prepare OpenTelemetry trace context to propagate to the subagent.
+            // We inject from the current active context so the subagent's root
+            // invocation span can be a child of whatever span is active when
+            // this Task tool runs (ideally the agent.tool_call span).
+            if (process.env.DEBUG_TELEMETRY === "true") {
+                console.log(`[querySubagent] Tool function executing for agent: ${agentPath}`);
+            }
+            const otelCarrier = {};
+            const activeCtx = context.active();
+            const activeSpan = trace.getSpan(activeCtx);
+            if (process.env.DEBUG_TELEMETRY === "true") {
+                console.log(`[querySubagent] Active span when tool executes:`, activeSpan?.spanContext());
+            }
+            const ctxForInjection = activeSpan
+                ? trace.setSpan(activeCtx, activeSpan)
+                : activeCtx;
+            propagation.inject(ctxForInjection, otelCarrier);
+            const hasOtelContext = Object.keys(otelCarrier).length > 0;
+            // Create a new session with subagent mode flag and OTEL trace context
             const sessionResponse = await connection?.newSession({
                 cwd: agentWorkingDirectory,
                 mcpServers: [],
                 _meta: {
                     [SUBAGENT_MODE_KEY]: true,
+                    ...(hasOtelContext ? { otelTraceContext: otelCarrier } : {}),
                 },
             });
             // Send the prompt

package/dist/scaffold/link-local.d.ts

@@ -0,0 +1 @@
+export declare function linkLocalPackages(projectPath: string): Promise<void>;

package/dist/scaffold/link-local.js

@@ -0,0 +1,54 @@
+import { exists } from "node:fs/promises";
+import { join } from "node:path";
+import { $ } from "bun";
+const PACKAGE_PATHS = {
+    "@townco/ui": "packages/ui",
+    "@townco/core": "packages/core",
+    "@townco/tsconfig": "packages/tsconfig",
+    "@townco/tui-template": "apps/tui",
+    "@townco/gui-template": "apps/gui",
+    "@townco/secret": "packages/secret",
+    "@townco/agent": "packages/agent",
+    "@townco/cli": "apps/cli",
+};
+async function getMonorepoRoot() {
+    try {
+        // 1. Get git repo root
+        const result = await $ `git rev-parse --show-toplevel`.quiet();
+        const repoRoot = result.text().trim();
+        // 2. Check package.json name === "town"
+        const pkgJsonPath = join(repoRoot, "package.json");
+        const pkgJson = await Bun.file(pkgJsonPath).json();
+        if (pkgJson.name !== "town")
+            return null;
+        // 3. Check packages/agent and packages/ui exist
+        const agentExists = await exists(join(repoRoot, "packages/agent"));
+        const uiExists = await exists(join(repoRoot, "packages/ui"));
+        if (!agentExists || !uiExists)
+            return null;
+        return repoRoot;
+    }
+    catch {
+        return null;
+    }
+}
+export async function linkLocalPackages(projectPath) {
+    const repoRoot = await getMonorepoRoot();
+    if (!repoRoot)
+        return; // Not in monorepo, no-op
+    console.log("Detected town monorepo, linking local packages...");
+    // 1. Register each local package globally
+    for (const [, localPath] of Object.entries(PACKAGE_PATHS)) {
+        const pkgPath = join(repoRoot, localPath);
+        await $ `bun link`.cwd(pkgPath).quiet();
+    }
+    // 2. Parse project's package.json for @townco/* deps
+    const pkgJson = await Bun.file(join(projectPath, "package.json")).json();
+    const deps = { ...pkgJson.dependencies, ...pkgJson.devDependencies };
+    const towncoPackages = Object.keys(deps).filter((name) => name.startsWith("@townco/"));
+    // 3. Link each package in the project
+    for (const pkgName of towncoPackages) {
+        await $ `bun link ${pkgName}`.cwd(projectPath);
+        console.log(`Linked ${pkgName}`);
+    }
+}

package/dist/scaffold/project-scaffold.js

@@ -21,6 +21,7 @@ function generateProjectPackageJson() {
             "@radix-ui/react-select": "^2.2.6",
             "@radix-ui/react-slot": "^1.2.4",
             "@radix-ui/react-tabs": "^1.1.13",
+            "@townco/core": "~0.0.23",
             "@townco/ui": "^0.1.0",
             "@townco/agent": "^0.1.20",
             "class-variance-authority": "^0.7.1",

package/dist/telemetry/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * OpenTelemetry integration for @townco/agent
+ * Provides tracing and logging capabilities for agent operations
+ */
+import { type Attributes, type Context, type Span, type Tracer } from "@opentelemetry/api";
+import { type Logger as OTelLogger } from "@opentelemetry/api-logs";
+export interface TelemetryConfig {
+    /** Enable telemetry (default: false) */
+    enabled?: boolean;
+    /** Service name for traces and logs (default: '@townco/agent') */
+    serviceName?: string;
+    /** Base attributes to attach to all spans and logs */
+    attributes?: Record<string, string | number>;
+    /** Custom tracer instance (optional, uses global registry if not provided) */
+    tracer?: Tracer;
+    /** Custom logger instance (optional, uses global registry if not provided) */
+    logger?: OTelLogger;
+}
+declare class AgentTelemetry {
+    private tracer;
+    private logger;
+    private enabled;
+    private serviceName;
+    private baseAttributes;
+    configure(config: TelemetryConfig): void;
+    /**
+     * Start a new span
+     * @param name - Span name
+     * @param attributes - Span attributes
+     * @param parentContext - Optional parent context (defaults to active context)
+     * @returns Span instance or null if telemetry is disabled
+     */
+    startSpan(name: string, attributes?: Attributes, parentContext?: Context): Span | null;
+    /**
+     * Make a span the active span and run a function within its context
+     */
+    withActiveSpan<T>(span: Span | null, fn: () => T): T;
+    /**
+     * Make a span the active span and run an async function within its context
+     */
+    withActiveSpanAsync<T>(span: Span | null, fn: () => Promise<T>): Promise<T>;
+    /**
+     * End a span with optional error
+     */
+    endSpan(span: Span | null, error?: Error): void;
+    /**
+     * Set attributes on a span
+     */
+    setSpanAttributes(span: Span | null, attributes: Attributes): void;
+    /**
+     * Log a message with optional attributes
+     */
+    log(level: "info" | "warn" | "error", message: string, attributes?: Attributes): void;
+    /**
+     * Record token usage metrics on a span
+     * Following OpenTelemetry GenAI semantic conventions:
+     * https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/
+     */
+    recordTokenUsage(inputTokens: number, outputTokens: number, span?: Span | null): void;
+}
+declare const telemetry: AgentTelemetry;
+/**
+ * Configure telemetry for all agents in this process
+ * Must be called before creating any agent runners
+ *
+ * @example
+ * ```typescript
+ * import { configureTelemetry } from '@townco/agent';
+ * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+ *
+ * // Set up OTel provider first
+ * const provider = new NodeTracerProvider();
+ * provider.register();
+ *
+ * // Enable telemetry
+ * configureTelemetry({
+ *   enabled: true,
+ *   serviceName: 'my-agent-app',
+ * });
+ * ```
+ */
+export declare function configureTelemetry(config: TelemetryConfig): void;
+export { telemetry };

package/dist/telemetry/index.js

@@ -0,0 +1,172 @@
+/**
+ * OpenTelemetry integration for @townco/agent
+ * Provides tracing and logging capabilities for agent operations
+ */
+import { context, SpanStatusCode, trace, } from "@opentelemetry/api";
+import { logs } from "@opentelemetry/api-logs";
+class AgentTelemetry {
+    tracer = null;
+    logger = null;
+    enabled = false;
+    serviceName = "@townco/agent";
+    baseAttributes = {};
+    configure(config) {
+        this.enabled = config.enabled ?? false;
+        this.serviceName = config.serviceName ?? this.serviceName;
+        this.baseAttributes = config.attributes ?? {};
+        if (this.enabled) {
+            // Use provided tracer/logger or get from global registry
+            this.tracer = config.tracer ?? trace.getTracer(this.serviceName);
+            this.logger = config.logger ?? logs.getLogger(this.serviceName);
+            // Debug logging
+            if (process.env.DEBUG_TELEMETRY === "true") {
+                console.log("[Telemetry] Configured:", {
+                    enabled: this.enabled,
+                    serviceName: this.serviceName,
+                    hasTracer: !!this.tracer,
+                    hasLogger: !!this.logger,
+                    baseAttributes: this.baseAttributes,
+                });
+            }
+        }
+    }
+    /**
+     * Start a new span
+     * @param name - Span name
+     * @param attributes - Span attributes
+     * @param parentContext - Optional parent context (defaults to active context)
+     * @returns Span instance or null if telemetry is disabled
+     */
+    startSpan(name, attributes, parentContext) {
+        if (!this.enabled || !this.tracer) {
+            return null;
+        }
+        // Use provided context or get the active one
+        const ctx = parentContext ?? context.active();
+        const span = this.tracer.startSpan(name, {
+            attributes: {
+                ...this.baseAttributes,
+                "service.name": this.serviceName,
+                ...attributes,
+            },
+        }, ctx);
+        // Debug logging
+        if (process.env.DEBUG_TELEMETRY === "true") {
+            const parentSpan = trace.getSpan(ctx);
+            const parentInfo = parentSpan
+                ? ` (parent: ${parentSpan.spanContext().spanId.slice(0, 8)})`
+                : " (root)";
+            console.log(`[Telemetry] Started span: ${name}${parentInfo}`, attributes);
+        }
+        return span;
+    }
+    /**
+     * Make a span the active span and run a function within its context
+     */
+    withActiveSpan(span, fn) {
+        if (!span) {
+            return fn();
+        }
+        return context.with(trace.setSpan(context.active(), span), fn);
+    }
+    /**
+     * Make a span the active span and run an async function within its context
+     */
+    async withActiveSpanAsync(span, fn) {
+        if (!span) {
+            return fn();
+        }
+        return context.with(trace.setSpan(context.active(), span), fn);
+    }
+    /**
+     * End a span with optional error
+     */
+    endSpan(span, error) {
+        if (!span)
+            return;
+        if (error) {
+            span.recordException(error);
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error.message,
+            });
+        }
+        else {
+            span.setStatus({ code: SpanStatusCode.OK });
+        }
+        span.end();
+        // Debug logging
+        if (process.env.DEBUG_TELEMETRY === "true") {
+            console.log(`[Telemetry] Ended span${error ? ` with error: ${error.message}` : ""}`);
+        }
+    }
+    /**
+     * Set attributes on a span
+     */
+    setSpanAttributes(span, attributes) {
+        if (!span)
+            return;
+        span.setAttributes(attributes);
+    }
+    /**
+     * Log a message with optional attributes
+     */
+    log(level, message, attributes) {
+        if (!this.enabled || !this.logger) {
+            return;
+        }
+        this.logger.emit({
+            severityText: level.toUpperCase(),
+            body: message,
+            attributes: {
+                ...this.baseAttributes,
+                ...attributes,
+            },
+        });
+    }
+    /**
+     * Record token usage metrics on a span
+     * Following OpenTelemetry GenAI semantic conventions:
+     * https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/
+     */
+    recordTokenUsage(inputTokens, outputTokens, span) {
+        if (!this.enabled)
+            return;
+        const attrs = {
+            "gen_ai.usage.input_tokens": inputTokens,
+            "gen_ai.usage.output_tokens": outputTokens,
+            "gen_ai.usage.total_tokens": inputTokens + outputTokens,
+        };
+        if (span) {
+            span.setAttributes(attrs);
+        }
+        this.log("info", "Token usage recorded", attrs);
+    }
+}
+// Singleton instance
+const telemetry = new AgentTelemetry();
+/**
+ * Configure telemetry for all agents in this process
+ * Must be called before creating any agent runners
+ *
+ * @example
+ * ```typescript
+ * import { configureTelemetry } from '@townco/agent';
+ * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+ *
+ * // Set up OTel provider first
+ * const provider = new NodeTracerProvider();
+ * provider.register();
+ *
+ * // Enable telemetry
+ * configureTelemetry({
+ *   enabled: true,
+ *   serviceName: 'my-agent-app',
+ * });
+ * ```
+ */
+export function configureTelemetry(config) {
+    telemetry.configure(config);
+}
+// Export singleton for internal use
+export { telemetry };

package/dist/telemetry/setup.d.ts

@@ -0,0 +1,22 @@
+/**
+ * OpenTelemetry provider setup for @townco/agent
+ * Initializes the trace provider, exporter, and propagator
+ */
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+export interface TelemetrySetupOptions {
+    serviceName?: string;
+    otlpEndpoint?: string;
+    debug?: boolean;
+}
+/**
+ * Initialize OpenTelemetry with OTLP exporter
+ * Call this early in your application startup
+ */
+export declare function initializeOpenTelemetry(options?: TelemetrySetupOptions): {
+    provider: NodeTracerProvider;
+    shutdown: () => Promise<void>;
+};
+/**
+ * Initialize OpenTelemetry from environment variables and register shutdown handlers
+ */
+export declare function initializeOpenTelemetryFromEnv(): void;

package/dist/telemetry/setup.js

@@ -0,0 +1,141 @@
+/**
+ * OpenTelemetry provider setup for @townco/agent
+ * Initializes the trace provider, exporter, and propagator
+ */
+import { propagation } from "@opentelemetry/api";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { Resource } from "@opentelemetry/resources";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { configureTelemetry } from "./index.js";
+/**
+ * Initialize OpenTelemetry with OTLP exporter
+ * Call this early in your application startup
+ */
+export function initializeOpenTelemetry(options = {}) {
+    const serviceName = options.serviceName ?? "@townco/agent";
+    const otlpEndpoint = options.otlpEndpoint ?? "http://localhost:4318";
+    const debug = options.debug ?? false;
+    // Note: When passing url in code, we must include the full path.
+    // The SDK only auto-appends /v1/traces when using OTEL_EXPORTER_OTLP_ENDPOINT env var.
+    const traceUrl = otlpEndpoint.endsWith("/")
+        ? `${otlpEndpoint}v1/traces`
+        : `${otlpEndpoint}/v1/traces`;
+    if (debug) {
+        console.log("Initializing OpenTelemetry...");
+        console.log(`Service name: ${serviceName}`);
+        console.log(`OTLP base endpoint: ${otlpEndpoint}`);
+        console.log(`OTLP trace URL: ${traceUrl}`);
+        // Quick connectivity test
+        fetch(otlpEndpoint.replace(/\/$/, "") + "/health")
+            .then((r) => r.json())
+            .then((d) => console.log(`✓ OTLP server reachable:`, d))
+            .catch((e) => console.error(`✗ OTLP server NOT reachable:`, e.message));
+    }
+    const provider = new NodeTracerProvider({
+        resource: new Resource({
+            [ATTR_SERVICE_NAME]: serviceName,
+        }),
+    });
+    // Configure exporter with logging wrapper
+    // Disable keep-alive to work around Bun's http module 'close' event timing issue
+    const baseExporter = new OTLPTraceExporter({
+        url: traceUrl,
+        httpAgentOptions: { keepAlive: false },
+    });
+    // Wrap exporter to add logging (matches SpanExporter interface)
+    const loggingExporter = {
+        export: async (spans, resultCallback) => {
+            if (debug) {
+                console.log(`📤 Exporting ${spans.length} span(s)...`);
+                for (const span of spans) {
+                    console.log(`   - ${span.name} (duration: ${span.duration}ms)`);
+                }
+            }
+            return baseExporter.export(spans, (result) => {
+                if (result.code === 0) {
+                    if (debug) {
+                        console.log(`✅ Successfully exported ${spans.length} span(s)`);
+                    }
+                }
+                else {
+                    // Bun has a bug where the 'close' event fires before 'end', causing
+                    // false "Request timed out" errors. The export usually succeeds anyway.
+                    // Only log non-timeout errors as actual errors.
+                    const errorMsg = result.error?.message ?? "";
+                    if (errorMsg.includes("timed out")) {
+                        if (debug) {
+                            console.log(`⚠️  Export reported timeout (Bun http bug - data likely sent successfully)`);
+                        }
+                    }
+                    else {
+                        console.error(`❌ Failed to export spans:`, result.error);
+                    }
+                }
+                resultCallback(result);
+            });
+        },
+        shutdown: () => baseExporter.shutdown(),
+    };
+    // Add batch span processor
+    const batchProcessor = new BatchSpanProcessor(loggingExporter, {
+        maxQueueSize: 100,
+        maxExportBatchSize: 10,
+        scheduledDelayMillis: 5000, // Export every 5 seconds (default)
+    });
+    provider.addSpanProcessor(batchProcessor);
+    // Register the provider globally
+    provider.register();
+    // Configure W3C Trace Context propagator for cross-process traces
+    propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+    // Now configure our telemetry wrapper
+    configureTelemetry({
+        enabled: true,
+        serviceName,
+        attributes: {
+            "agent.environment": process.env.NODE_ENV ?? "development",
+        },
+    });
+    if (debug) {
+        console.log("✓ OpenTelemetry fully initialized");
+    }
+    // Return shutdown function for graceful cleanup
+    const shutdown = async () => {
+        try {
+            await provider.forceFlush();
+            await provider.shutdown();
+            if (debug) {
+                console.log("✓ Telemetry flushed");
+            }
+        }
+        catch (error) {
+            console.error("Error flushing telemetry:", error);
+        }
+    };
+    return { provider, shutdown };
+}
+/**
+ * Initialize OpenTelemetry from environment variables and register shutdown handlers
+ */
+export function initializeOpenTelemetryFromEnv() {
+    const debug = process.env.DEBUG_TELEMETRY === "true";
+    const { shutdown } = initializeOpenTelemetry({
+        serviceName: process.env.OTEL_SERVICE_NAME ?? "@townco/agent",
+        otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318",
+        debug,
+    });
+    // Register graceful shutdown handlers
+    process.on("SIGINT", async () => {
+        await shutdown();
+        process.exit(0);
+    });
+    process.on("SIGTERM", async () => {
+        await shutdown();
+        process.exit(0);
+    });
+    process.on("beforeExit", async () => {
+        await shutdown();
+    });
+}