netra-zen 1.0.2__tar.gz → 1.0.4__tar.gz

{netra_zen-1.0.2/netra_zen.egg-info → netra_zen-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netra-zen
-Version: 1.0.2
+Version: 1.0.4
 Summary: Multi-instance Claude orchestrator for parallel task execution
 Home-page: https://github.com/netra-systems/zen
 Author:  Systems

{netra_zen-1.0.2 → netra_zen-1.0.4/netra_zen.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netra-zen
-Version: 1.0.2
+Version: 1.0.4
 Summary: Multi-instance Claude orchestrator for parallel task execution
 Home-page: https://github.com/netra-systems/zen
 Author:  Systems

{netra_zen-1.0.2 → netra_zen-1.0.4}/netra_zen.egg-info/SOURCES.txt

@@ -40,4 +40,8 @@ token_budget/budget_manager.py
 token_budget/models.py
 token_budget/visualization.py
 token_transparency/__init__.py
-token_transparency/claude_pricing_engine.py
+token_transparency/claude_pricing_engine.py
+zen/__init__.py
+zen/telemetry/__init__.py
+zen/telemetry/embedded_credentials.py
+zen/telemetry/manager.py

{netra_zen-1.0.2 → netra_zen-1.0.4}/netra_zen.egg-info/top_level.txt

@@ -1,4 +1,5 @@
 agent_interface
 token_budget
 token_transparency
+zen
 zen_orchestrator

{netra_zen-1.0.2 → netra_zen-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "netra-zen"
-version = "1.0.2"
+version = "1.0.4"
 description = "Multi-instance Claude orchestrator for parallel task execution"
 readme = "README.md"
 authors = [
@@ -58,7 +58,7 @@ zen = "zen_orchestrator:run"
 
 [tool.setuptools]
 py-modules = ["zen_orchestrator"]
-packages = ["agent_interface", "token_budget", "token_transparency"]
+packages = ["agent_interface", "token_budget", "token_transparency", "zen", "zen.telemetry"]
 
 [tool.setuptools.package-data]
 "*" = ["*.json", "*.yaml", "*.yml", "*.md"]

{netra_zen-1.0.2 → netra_zen-1.0.4}/setup.py

@@ -8,7 +8,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="netra-zen",
-    version="1.0.2",
+    version="1.0.4",
     author=" Systems",
     author_email="pypi@netrasystems.ai",
     description="Multi-instance Claude orchestrator for parallel task execution",

netra_zen-1.0.4/zen/__init__.py

@@ -0,0 +1,7 @@
+"""Zen namespace package placeholder.
+
+This lightweight module exists so repository scripts can import
+`zen.telemetry` directly without requiring the full orchestrator package.
+"""
+
+__all__: list[str] = []

netra_zen-1.0.4/zen/telemetry/__init__.py

@@ -0,0 +1,11 @@
+"""Telemetry utilities exposed by the Zen package."""
+
+from .embedded_credentials import get_embedded_credentials, get_project_id
+from .manager import TelemetryManager, telemetry_manager
+
+__all__ = [
+    "TelemetryManager",
+    "telemetry_manager",
+    "get_embedded_credentials",
+    "get_project_id",
+]

netra_zen-1.0.4/zen/telemetry/embedded_credentials.py

@@ -0,0 +1,26 @@
+"""Embedded telemetry credentials. AUTO-GENERATED - DO NOT COMMIT."""
+
+import base64
+import json
+from google.oauth2 import service_account
+
+_EMBEDDED_CREDENTIALS_B64 = 'ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAibmV0cmEtdGVsZW1ldHJ5LXB1YmxpYyIsCiAgInByaXZhdGVfa2V5X2lkIjogImVjOWM4ZGNlZGZmMTUzNjM5YTUxOTcyMzc0MjYyNjkwNjZkNzAxYTQiLAogICJwcml2YXRlX2tleSI6ICItLS0tLUJFR0lOIFBSSVZBVEUgS0VZLS0tLS1cbk1JSUV2Z0lCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktnd2dnU2tBZ0VBQW9JQkFRREhUcmZFOHlQdUFCTDNcbk5aS3diZ1AwamRyaWRnY0UwMUlLMks1YkZ1bWFrUHVrRGxzV0dVaUswOXEyaVNYTWVUQmJPZDF0VjFoc3VJcUhcbnpQK0pZd0NTcVp4S0pIQS8yWUdVcERqeWhHRVd3QTNtS3laVXVUUS9yUTBUK20yV0cwdEMxUzBpQzB6U211cEpcbjBNeGhUUDRjKzYreEczSDVSWEF1YjdONmx6eFFWVnJSY3FHMTYydlF5SFA2OWIrd2RidTJHM0o5UkJVN1VUK1FcbkU2RHB2K01YaEp3MnRPdHZLbFBQT3BnWm9Sb0pmeXU1WlpzbHlJZCtzY3FhUTY5ZjBaSmpIRjlYQVdlT25mUTRcbmExbmV0LzJqRjZibWpuZmQ2MjhBODA5cEluTXJEL0FwZjJzUWJJdXJIYUI4am5uTEQ0eDMrbVhXRTgyMFJLNktcbjViZ0FQanNoQWdNQkFBRUNnZ0VBQmZERVZMWVlDakFkb0pscnpyOHF0a056cEpnV3Y3ZXlQSEZHcWgraDFSbndcbjdDd0Mza0xnNlFWbFFaZFBKWHZ2dTJwYlBaYnl3MlBST2ppN25adFNNU3pseEFaM3c0bHV2YkRTNHpTYnBiZFJcbityd3F3Mi8xUFJnaCtZaFhjNWZLNjVvcHd4Zmg0VzJkWWRlYnZlTXkrRWR1cmtsV2dYTG13L1dQbkkzdExlbzlcbjV1elZjbU42Qk04YkU3azFYK1M0RURBS0VRWlprUEdzTFQ4RXN4UmdWOWtnT1Zicm5VQ1Z0dXA1Q0NGbUR3U1Bcbmg0U25wMEsvTUp3b1U3NG4reTlFMXYxUXRnajE5TkhaNHJ2dFpnUlVaandHQy9Cc3ZkcE1PazArZTJEMlgvRk9cblZnc29xS2tDaklWUzRMcG5YSEpZbU5oajZWNHRXUnZ1OW1NTXhTL3FBUUtCZ1FEb3hZenlsdEZKL242ZEQvUHlcbnZLOFRaTHd5dFdCcjBXU3ZHU2VzM0JYRGZoKzBFbU4rRHpnZGdUb0ovbkhpazM5R21QM0tLN2htOFVvaFFHRy9cbkh0SFRuS0lBQlhrSU8yd2Z3N0h0V2pPTXRocHp2dFQxcmVEVHVjVk0wc2lCMHpjTldCMjFUamdQL3JYY2Q3NWVcbklERmNBN0hTbUJDLzB4bzk3aC8wV2YvOW9RS0JnUURiTWtnbjlVR2Y2SVRMNmxTcDdrYWJGL0NuaE4yU2VTMVdcbnd3R21iRThxTTU0UitDcVRUeHk2UHBRaFVSczlHM1VpVmQ1SXZWVDhuT095ZVBZVFJEbnFCYjJ4S214SFRodlZcbnVQcTgwQXB3anBMbzh6VkFDSy9iVFVjSmlKVGFBdXFHaXI1Ykc4YUlldVpIc0pLeWJ1NmhoNkhXMldwWXVVV1BcbkZ3TTl4elpOZ1FLQmdRQzg5dHJVZVJFUVE3VGZwbnJBM09JNEdUZ2E1bG1QVFo2eDh2YmRncEY4Y2FBbEhDUitcbnlyWWdaYThMTysrU0kzRllpNHpFR2pnS0FlblBFcWdIY21xZW9uSjFGL3hJYll6NlFIRHFJYWJsblZQZUVOWnJcblY2dkQxZlRReC9FVVM3Wk9jL0V5Slh5bnAzeFZyVFB5ejZtaWJERm9xQ0E0eVpSdElDbjZ3VEZxNFFLQmdFWFJcbnAxQXErOE0rb2dYOTF3ZmxvTkhIOTF5MG9vc0VWQis5cjZuZDkvMWVRYXhCbXZZZkRleDVBRi80WUsrL0xqbElcbmxxd2V1cEpZT3VMZlNxcHFZZlFiN2djZmx5dkRRblI2SGt2RURIODd1cW0reGlobVcvV0RrT3dGZUR4VkQzVFpcbmZyYXdpelZ2eUNmdm8xcDRvVVFNV3MxL3BUTXJtRzl5aWhMRWdKU0JBb0dCQU1GWm50ZUtUUDZrVVdrVmpOcndcbmUvQzBDbjJ6dk1YNXVnZURkS1FWNkwrY25mRWlRSzdzZ3R5eFp5ek5kMC82QXJ0YnBrcS9wcVlaYXpwVzVFMkxcbkxVMUF3MmdHT25GRlh2ZXg4aXpOZXViMGdvUVE4d3BtL3lrMVNVekR6VTV1dCtPbVFFRmpsbUYrNDkza0ZYcC9cbnc1MWh2WjVVL2loL1NYbjN6cjdEWE5QYlxuLS0tLS1FTkQgUFJJVkFURSBLRVktLS0tLVxuIiwKICAiY2xpZW50X2VtYWlsIjogInplbi1jb21tdW5pdHktdGVsZW1ldHJ5QG5ldHJhLXRlbGVtZXRyeS1wdWJsaWMuaWFtLmdzZXJ2aWNlYWNjb3VudC5jb20iLAogICJjbGllbnRfaWQiOiAiMTE0NzAwMDA0NzA1MDUxODg5NTY4IiwKICAiYXV0aF91cmkiOiAiaHR0cHM6Ly9hY2NvdW50cy5nb29nbGUuY29tL28vb2F1dGgyL2F1dGgiLAogICJ0b2tlbl91cmkiOiAiaHR0cHM6Ly9vYXV0aDIuZ29vZ2xlYXBpcy5jb20vdG9rZW4iLAogICJhdXRoX3Byb3ZpZGVyX3g1MDlfY2VydF91cmwiOiAiaHR0cHM6Ly93d3cuZ29vZ2xlYXBpcy5jb20vb2F1dGgyL3YxL2NlcnRzIiwKICAiY2xpZW50X3g1MDlfY2VydF91cmwiOiAiaHR0cHM6Ly93d3cuZ29vZ2xlYXBpcy5jb20vcm9ib3QvdjEvbWV0YWRhdGEveDUwOS96ZW4tY29tbXVuaXR5LXRlbGVtZXRyeSU0MG5ldHJhLXRlbGVtZXRyeS1wdWJsaWMuaWFtLmdzZXJ2aWNlYWNjb3VudC5jb20iLAogICJ1bml2ZXJzZV9kb21haW4iOiAiZ29vZ2xlYXBpcy5jb20iCn0K'
+_CREDENTIALS_DICT = json.loads(
+    base64.b64decode(_EMBEDDED_CREDENTIALS_B64.encode("utf-8"))
+)
+
+
+def get_embedded_credentials():
+    """Return service account credentials."""
+    try:
+        return service_account.Credentials.from_service_account_info(
+            _CREDENTIALS_DICT,
+            scopes=["https://www.googleapis.com/auth/trace.append"],
+        )
+    except Exception:
+        return None
+
+
+def get_project_id() -> str:
+    """Return GCP project ID."""
+    return _CREDENTIALS_DICT.get("project_id", 'netra-telemetry-public')

netra_zen-1.0.4/zen/telemetry/manager.py

@@ -0,0 +1,249 @@
+"""Telemetry manager for Zen orchestrator.
+
+Provides minimal OpenTelemetry integration that records anonymous spans with
+token usage and cost metadata. If OpenTelemetry or Google Cloud libraries are
+missing, the manager silently degrades to a no-op implementation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import re
+from dataclasses import asdict
+from typing import Any, Dict, Optional
+
+try:
+    from opentelemetry import trace
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    from opentelemetry.trace import SpanKind
+
+    OPENTELEMETRY_AVAILABLE = True
+except ImportError:  # pragma: no cover - optional dependency
+    OPENTELEMETRY_AVAILABLE = False
+
+try:
+    from google.cloud.trace_v2 import TraceServiceClient
+    from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
+    from google.api_core.exceptions import GoogleAPICallError  # type: ignore
+
+    GCP_EXPORT_AVAILABLE = True
+except ImportError:  # pragma: no cover - optional dependency
+    GCP_EXPORT_AVAILABLE = False
+
+    class GoogleAPICallError(Exception):  # type: ignore
+        """Fallback exception used when google-api-core is unavailable."""
+
+        pass
+
+from .embedded_credentials import get_embedded_credentials, get_project_id
+
+logger = logging.getLogger(__name__)
+
+
+def _sanitize_tool_name(tool: str) -> str:
+    """Convert tool names to telemetry-safe attribute suffixes."""
+    safe = re.sub(r"[^a-z0-9_]+", "_", tool.lower()).strip("_")
+    return safe or "tool"
+
+
+class _NoOpTelemetryManager:
+    """Fallback manager when telemetry dependencies are unavailable."""
+
+    def is_enabled(self) -> bool:
+        return False
+
+    def record_instance_span(self, *_, **__):  # pragma: no cover - trivial
+        return
+
+    def shutdown(self) -> None:  # pragma: no cover - trivial
+        return
+
+
+class TelemetryManager:
+    """Manage OpenTelemetry setup and span emission for Zen."""
+
+    def __init__(self) -> None:
+        self._enabled = False
+        self._provider: Optional[TracerProvider] = None
+        self._tracer = None
+        self._initialize()
+
+    def _initialize(self) -> None:
+        if os.getenv("ZEN_TELEMETRY_DISABLED", "").lower() in {"1", "true", "yes"}:
+            logger.debug("Telemetry disabled via ZEN_TELEMETRY_DISABLED")
+            return
+
+        if not (OPENTELEMETRY_AVAILABLE and GCP_EXPORT_AVAILABLE):
+            logger.debug("OpenTelemetry or Google Cloud exporter not available; telemetry disabled")
+            return
+
+        credentials = get_embedded_credentials()
+        if credentials is None:
+            logger.debug("No telemetry credentials detected; telemetry disabled")
+            return
+
+        try:
+            project_id = get_project_id()
+            client = TraceServiceClient(credentials=credentials)
+            exporter = CloudTraceSpanExporter(project_id=project_id, client=client)
+
+            resource_attrs = {
+                "service.name": "zen-orchestrator",
+                "service.version": os.getenv("ZEN_VERSION", "1.0.3"),
+                "telemetry.sdk.language": "python",
+                "telemetry.sdk.name": "opentelemetry",
+                "zen.analytics.type": "community",
+            }
+
+            resource = Resource.create(resource_attrs)
+            provider = TracerProvider(resource=resource)
+            provider.add_span_processor(BatchSpanProcessor(exporter))
+
+            trace.set_tracer_provider(provider)
+            self._provider = provider
+            self._tracer = trace.get_tracer("zen.telemetry")
+            self._enabled = True
+            logger.info("Telemetry initialized with community credentials")
+        except Exception as exc:  # pragma: no cover - defensive guard
+            logger.warning(f"Failed to initialize telemetry: {exc}")
+            self._enabled = False
+            self._provider = None
+            self._tracer = None
+
+    # Public API -----------------------------------------------------
+
+    def is_enabled(self) -> bool:
+        return self._enabled and self._tracer is not None
+
+    def record_instance_span(
+        self,
+        batch_id: str,
+        instance_name: str,
+        status: Any,
+        config: Any,
+        cost_usd: Optional[float] = None,
+        workspace: Optional[str] = None,
+    ) -> None:
+        if not self.is_enabled():
+            return
+
+        assert self._tracer is not None  # mypy hint
+
+        attributes: Dict[str, Any] = {
+            "zen.batch.id": batch_id,
+            "zen.instance.name": instance_name,
+            "zen.instance.status": getattr(status, "status", "unknown"),
+            "zen.instance.success": getattr(status, "status", "") == "completed",
+            "zen.instance.permission_mode": getattr(config, "permission_mode", "unknown"),
+            "zen.instance.tool_calls": getattr(status, "tool_calls", 0),
+            "zen.tokens.total": getattr(status, "total_tokens", 0),
+            "zen.tokens.input": getattr(status, "input_tokens", 0),
+            "zen.tokens.output": getattr(status, "output_tokens", 0),
+            "zen.tokens.cache.read": getattr(status, "cache_read_tokens", 0),
+            "zen.tokens.cache.creation": getattr(status, "cache_creation_tokens", 0),
+            "zen.tokens.cached_total": getattr(status, "cached_tokens", 0),
+        }
+
+        start_time = getattr(status, "start_time", None)
+        end_time = getattr(status, "end_time", None)
+        if start_time and end_time:
+            attributes["zen.instance.duration_ms"] = int((end_time - start_time) * 1000)
+
+        command = getattr(config, "command", None) or getattr(config, "prompt", None)
+        if isinstance(command, str) and command.startswith("/"):
+            attributes["zen.instance.command_type"] = "slash"
+            attributes["zen.instance.command"] = command
+        elif isinstance(command, str):
+            attributes["zen.instance.command_type"] = "prompt"
+        else:
+            attributes["zen.instance.command_type"] = "unknown"
+
+        session_id = getattr(config, "session_id", None)
+        if session_id:
+            session_hash = hashlib.sha256(session_id.encode("utf-8")).hexdigest()[:16]
+            attributes["zen.session.hash"] = session_hash
+
+        if workspace:
+            workspace_hash = hashlib.sha256(workspace.encode("utf-8")).hexdigest()[:16]
+            attributes["zen.workspace.hash"] = workspace_hash
+
+        # Tool metadata
+        tool_tokens = getattr(status, "tool_tokens", {}) or {}
+        attributes["zen.tools.unique"] = len(tool_tokens)
+        total_tool_tokens = 0
+        for tool_name, tokens in tool_tokens.items():
+            sanitized = _sanitize_tool_name(tool_name)
+            attributes[f"zen.tools.tokens.{sanitized}"] = int(tokens)
+            total_tool_tokens += int(tokens)
+        attributes["zen.tokens.tools_total"] = total_tool_tokens
+
+        tool_details = getattr(status, "tool_details", {}) or {}
+        for tool_name, count in tool_details.items():
+            sanitized = _sanitize_tool_name(tool_name)
+            attributes[f"zen.tools.invocations.{sanitized}"] = int(count)
+
+        # Cost metadata
+        if cost_usd is not None:
+            attributes["zen.cost.usd_total"] = round(float(cost_usd), 6)
+
+        reported_cost = getattr(status, "total_cost_usd", None)
+        if reported_cost is not None:
+            attributes["zen.cost.usd_reported"] = round(float(reported_cost), 6)
+
+        # Derive cost components using fallback pricing (USD per million tokens)
+        input_tokens = getattr(status, "input_tokens", 0)
+        output_tokens = getattr(status, "output_tokens", 0)
+        cache_read_tokens = getattr(status, "cache_read_tokens", 0)
+        cache_creation_tokens = getattr(status, "cache_creation_tokens", 0)
+
+        input_cost = (input_tokens / 1_000_000) * 3.00
+        output_cost = (output_tokens / 1_000_000) * 15.00
+        cache_read_cost = (cache_read_tokens / 1_000_000) * (3.00 * 0.1)
+        cache_creation_cost = (cache_creation_tokens / 1_000_000) * (3.00 * 1.25)
+        tool_cost = (total_tool_tokens / 1_000_000) * 3.00
+
+        attributes.update(
+            {
+                "zen.cost.usd_input": round(input_cost, 6),
+                "zen.cost.usd_output": round(output_cost, 6),
+                "zen.cost.usd_cache_read": round(cache_read_cost, 6),
+                "zen.cost.usd_cache_creation": round(cache_creation_cost, 6),
+                "zen.cost.usd_tools": round(tool_cost, 6),
+            }
+        )
+
+        # Emit span
+        try:
+            with self._tracer.start_as_current_span(
+                "zen.instance", kind=SpanKind.INTERNAL
+            ) as span:
+                for key, value in attributes.items():
+                    span.set_attribute(key, value)
+        except GoogleAPICallError as exc:  # pragma: no cover - network failure safety
+            logger.warning(f"Failed to export telemetry span: {exc}")
+
+    def shutdown(self) -> None:
+        if not self._provider:
+            return
+        try:
+            if hasattr(self._provider, "force_flush"):
+                self._provider.force_flush()
+            if hasattr(self._provider, "shutdown"):
+                self._provider.shutdown()
+        except Exception as exc:  # pragma: no cover
+            logger.debug(f"Telemetry shutdown warning: {exc}")
+
+
+def _build_manager() -> TelemetryManager | _NoOpTelemetryManager:
+    if not (OPENTELEMETRY_AVAILABLE and GCP_EXPORT_AVAILABLE):
+        return _NoOpTelemetryManager()
+    return TelemetryManager()
+
+
+telemetry_manager = _build_manager()
+
+__all__ = ["TelemetryManager", "telemetry_manager"]

{netra_zen-1.0.2 → netra_zen-1.0.4}/zen_orchestrator.py

@@ -2,41 +2,43 @@
 """
 Usage Examples:
 
+  zen -h  # Help
+
 Direct Command Execution:
-  python zen_orchestrator.py "/help"  # Execute single command directly
-  python zen_orchestrator.py "/analyze-code" --workspace ~/my-project
-  python zen_orchestrator.py "/debug-issue" --instance-name "debug-session"
-  python zen_orchestrator.py "/optimize-performance" --session-id "perf-1"
-  python zen_orchestrator.py "/generate-docs" --clear-history --compact-history
+  zen "/single-command-in-claude-commands"  # Execute single command directly
+  zen "/analyze-code" --workspace ~/my-project
+  zen "/debug-issue" --instance-name "debug-session"
+  zen "/optimize-performance" --session-id "perf-1"
+  zen "/generate-docs" --clear-history --compact-history
 
 Configuration File Mode:
-  python zen_orchestrator.py --config config.json
-  python zen_orchestrator.py --config config.json --workspace ~/my-project
+  zen --config config.json
+  zen --config config.json --workspace ~/my-project
 
 Default Instances Mode:
-  python zen_orchestrator.py --dry-run  # Auto-detects workspace from project root
-  python zen_orchestrator.py --workspace ~/my-project --dry-run  # Override workspace
-  python zen_orchestrator.py --startup-delay 2.0  # 2 second delay between launches
-  python zen_orchestrator.py --startup-delay 0.5  # 0.5 second delay between launches
-  python zen_orchestrator.py --max-line-length 1000  # Longer output lines
-  python zen_orchestrator.py --status-report-interval 60  # Status reports every 60s
-  python zen_orchestrator.py --quiet  # Minimal output, errors only
+  zen --dry-run  # Auto-detects workspace from project root
+  zen --workspace ~/my-project --dry-run  # Override workspace
+  zen --startup-delay 2.0  # 2 second delay between launches
+  zen --startup-delay 0.5  # 0.5 second delay between launches
+  zen --max-line-length 1000  # Longer output lines
+  zen --status-report-interval 60  # Status reports every 60s
+  zen --quiet  # Minimal output, errors only
 
 Command Discovery:
-  python zen_orchestrator.py --list-commands  # Show all available commands
-  python zen_orchestrator.py --inspect-command "/analyze-code"  # Inspect specific command
+  zen --list-commands  # Show all available commands
+  zen --inspect-command "/analyze-code"  # Inspect specific command
 
 Scheduling:
-  python zen_orchestrator.py "/analyze-code" --start-at "2h"  # Start 2 hours from now
-  python zen_orchestrator.py "/debug-issue" --start-at "30m"  # Start in 30 minutes
-  python zen_orchestrator.py "/optimize" --start-at "1am"  # Start at 1 AM (today or tomorrow)
-  python zen_orchestrator.py "/review-code" --start-at "14:30"  # Start at 2:30 PM (today or tomorrow)
-  python zen_orchestrator.py "/generate-docs" --start-at "10:30pm"  # Start at 10:30 PM (today or tomorrow)
+  zen "/analyze-code" --start-at "2h"  # Start 2 hours from now
+  zen "/debug-issue" --start-at "30m"  # Start in 30 minutes
+  zen "/optimize" --start-at "1am"  # Start at 1 AM (today or tomorrow)
+  zen "/review-code" --start-at "14:30"  # Start at 2:30 PM (today or tomorrow)
+  zen "/generate-docs" --start-at "10:30pm"  # Start at 10:30 PM (today or tomorrow)
 
 Precedence Rules:
-  1. Direct command (highest) - python zen_orchestrator.py "/command"
-  2. Config file (medium) - python zen_orchestrator.py --config file.json
-  3. Default instances (lowest) - python zen_orchestrator.py
+  1. Direct command (highest) - zen "/command"
+  2. Config file (medium) - zen --config file.json    # expected default usage pattern
+  3. Default instances (lowest) - zen
 """
 
 import asyncio
@@ -58,6 +60,11 @@ import re
 from uuid import uuid4, UUID
 from enum import Enum
 
+try:
+    from zen.telemetry import telemetry_manager
+except Exception:  # pragma: no cover - telemetry optional
+    telemetry_manager = None
+
 # Add token budget imports with proper path handling
 sys.path.insert(0, str(Path(__file__).parent))
 try:
@@ -77,15 +84,6 @@ except ImportError as e:
     ClaudePricingEngine = None
     TokenUsageData = None
 
-# Add CLI extensions imports
-try:
-    from cli_extensions import handle_example_commands
-except ImportError as e:
-    # Graceful fallback if CLI extensions are not available
-    handle_example_commands = None
-
-# NetraOptimizer database functionality has been removed for security
-# Local token metrics are preserved without database persistence
 
 # Setup logging
 logging.basicConfig(
@@ -197,6 +195,7 @@ class InstanceStatus:
     tool_details: Dict[str, int] = None  # Tool name -> usage count
     tool_tokens: Dict[str, int] = None   # Tool name -> token usage
     tool_id_mapping: Dict[str, str] = field(default_factory=dict)  # tool_use_id -> tool name mapping
+    telemetry_recorded: bool = False
 
     def __post_init__(self):
         """Initialize fields that need special handling"""
@@ -214,7 +213,7 @@ class ClaudeInstanceOrchestrator:
 
     def __init__(self, workspace_dir: Path, max_console_lines: int = 5, startup_delay: float = 1.0,
                  max_line_length: int = 500, status_report_interval: int = 30,
-                 use_cloud_sql: bool = False, quiet: bool = False,
+                 quiet: bool = False,
                  overall_token_budget: Optional[int] = None,
                  overall_cost_budget: Optional[float] = None,
                  budget_type: str = "tokens",
@@ -233,11 +232,10 @@ class ClaudeInstanceOrchestrator:
         self.status_report_interval = status_report_interval  # Seconds between status reports
         self.last_status_report = time.time()
         self.status_report_task = None  # For the rolling status report task
-        self.use_cloud_sql = use_cloud_sql
         self.quiet = quiet
         self.log_level = log_level
         self.batch_id = str(uuid4())  # Generate batch ID for this orchestration run
-        # Database client removed for security - local metrics only
+        
         self.optimizer = None
 
         # Initialize budget manager if any budget settings are provided
@@ -278,12 +276,6 @@ class ClaudeInstanceOrchestrator:
         else:
             logger.debug("Token budget tracking disabled (no budget specified)")
 
-        # Configure CloudSQL if requested
-        # CloudSQL functionality available with Netra Apex
-        # Token metrics are now handled locally without database persistence
-        if use_cloud_sql:
-            logger.warning("CloudSQL functionality has been disabled. Token metrics will be displayed locally only.")
-            logger.info("For data persistence, consider upgrading to Netra Apex.")
 
     def log_at_level(self, level: LogLevel, message: str, log_func=None):
         """Log message only if current log level permits."""
@@ -338,36 +330,36 @@ class ClaudeInstanceOrchestrator:
         command_string = "; ".join(full_command)
 
         # Find the claude executable with Mac-specific paths
-        claude_cmd = shutil.which("claude")
+        # IMPORTANT: Use direct paths to avoid shell functions that may have database dependencies
+        possible_paths = [
+            "/opt/homebrew/bin/claude",  # Mac Homebrew ARM - prefer direct path
+            "/usr/local/bin/claude",     # Mac Homebrew Intel
+            "~/.local/bin/claude",       # User local install
+            "/usr/bin/claude",           # System install
+            "claude.cmd",                # Windows
+            "claude.exe",                # Windows
+        ]
+
+        claude_cmd = None
+        for path in possible_paths:
+            # Expand user path if needed
+            expanded_path = Path(path).expanduser()
+            if expanded_path.exists() and expanded_path.is_file():
+                claude_cmd = str(expanded_path)
+                logger.info(f"Found Claude executable at: {claude_cmd}")
+                break
+
+        # Only use shutil.which as fallback if no direct path found
         if not claude_cmd:
-            # Try common paths on different platforms
-            possible_paths = [
-                "claude.cmd",  # Windows
-                "claude.exe",  # Windows
-                "/opt/homebrew/bin/claude",  # Mac Homebrew ARM
-                "/usr/local/bin/claude",     # Mac Homebrew Intel
-                "~/.local/bin/claude",       # User local install
-                "/usr/bin/claude",           # System install
-                "claude"                     # Final fallback
-            ]
-            
-            for path in possible_paths:
-                # Expand user path if needed
-                expanded_path = Path(path).expanduser()
-                if expanded_path.exists():
-                    claude_cmd = str(expanded_path)
-                    logger.info(f"Found Claude executable at: {claude_cmd}")
-                    break
-                elif shutil.which(path):
-                    claude_cmd = path
-                    logger.info(f"Found Claude executable via which: {claude_cmd}")
-                    break
+            claude_cmd = shutil.which("claude")
+            if claude_cmd:
+                logger.info(f"Found Claude executable via which: {claude_cmd}")
 
-            if not claude_cmd or claude_cmd == "claude":
-                logger.warning("Claude command not found in PATH or common locations")
-                logger.warning("Please ensure Claude Code is installed and in your PATH")
-                logger.warning("Install with: npm install -g @anthropic/claude-code")
-                claude_cmd = "claude"  # Fallback
+        if not claude_cmd:
+            logger.warning("Claude command not found in PATH or common locations")
+            logger.warning("Please ensure Claude Code is installed and in your PATH")
+            logger.warning("Install with: npm install -g @anthropic/claude-code")
+            claude_cmd = "/opt/homebrew/bin/claude"  # Default fallback to most likely location
 
         # New approach: slash commands can be included directly in prompt
         cmd = [
@@ -494,6 +486,11 @@ class ClaudeInstanceOrchestrator:
                     logger.error(f"🚫 BLOCK MODE: {message}")
                     status.status = "failed"
                     status.error = f"Blocked by budget limit - {reason}"
+                    timestamp = time.time()
+                    if status.start_time is None:
+                        status.start_time = timestamp
+                    status.end_time = timestamp
+                    self._emit_instance_telemetry(name, config, status)
                     return False
                 else:  # warn mode
                     logger.warning(f"⚠️  WARN MODE: {message}")
@@ -571,18 +568,22 @@ class ClaudeInstanceOrchestrator:
             if returncode == 0:
                 status.status = "completed"
                 logger.info(f"Instance {name} completed successfully")
+                self._emit_instance_telemetry(name, config, status)
                 return True
             else:
                 status.status = "failed"
                 logger.error(f"Instance {name} failed with return code {returncode}")
                 if status.error:
                     logger.error(f"Error output: {status.error}")
+                self._emit_instance_telemetry(name, config, status)
                 return False
 
         except Exception as e:
             status.status = "failed"
             status.error = str(e)
             logger.error(f"Exception running instance {name}: {e}")
+            status.end_time = status.end_time or time.time()
+            self._emit_instance_telemetry(name, config, status)
             return False
 
     async def _save_metrics_to_database(self, name: str, config: InstanceConfig, status: InstanceStatus):
@@ -635,6 +636,38 @@ class ClaudeInstanceOrchestrator:
 
         return input_cost + output_cost + cache_read_cost + cache_creation_cost + tool_cost
 
+    def _emit_instance_telemetry(self, name: str, config: InstanceConfig, status: InstanceStatus) -> None:
+        """Send telemetry span with token usage and cost metadata."""
+
+        if telemetry_manager is None or not hasattr(telemetry_manager, "is_enabled"):
+            return
+
+        if getattr(status, "telemetry_recorded", False):
+            return
+
+        if not telemetry_manager.is_enabled():
+            return
+
+        cost_usd: Optional[float]
+        try:
+            cost_usd = self._calculate_cost(status)
+        except Exception as exc:  # pragma: no cover - defensive guard
+            logger.debug(f"Cost calculation failed for telemetry span ({name}): {exc}")
+            cost_usd = None
+
+        try:
+            telemetry_manager.record_instance_span(
+                batch_id=self.batch_id,
+                instance_name=name,
+                status=status,
+                config=config,
+                cost_usd=cost_usd,
+                workspace=str(self.workspace_dir),
+            )
+            status.telemetry_recorded = True
+        except Exception as exc:  # pragma: no cover - Network/export errors
+            logger.debug(f"Telemetry emission failed for {name}: {exc}")
+
     async def _stream_output(self, name: str, process):
         """Stream output in real-time for stream-json format (DEPRECATED - use _stream_output_parallel)"""
         status = self.statuses[name]
@@ -810,13 +843,19 @@ class ClaudeInstanceOrchestrator:
         for name, result in zip(self.instances.keys(), results):
             if isinstance(result, asyncio.TimeoutError):
                 logger.error(f"Instance {name} timed out after {timeout}s")
-                self.statuses[name].status = "failed"
-                self.statuses[name].error = f"Timeout after {timeout}s"
+                status = self.statuses[name]
+                status.status = "failed"
+                status.error = f"Timeout after {timeout}s"
+                status.end_time = time.time()
+                self._emit_instance_telemetry(name, self.instances[name], status)
                 final_results[name] = False
             elif isinstance(result, Exception):
                 logger.error(f"Instance {name} failed with exception: {result}")
-                self.statuses[name].status = "failed"
-                self.statuses[name].error = str(result)
+                status = self.statuses[name]
+                status.status = "failed"
+                status.error = str(result)
+                status.end_time = time.time()
+                self._emit_instance_telemetry(name, self.instances[name], status)
                 final_results[name] = False
             else:
                 final_results[name] = result
@@ -2370,8 +2409,6 @@ async def main():
                        help="Seconds between rolling status reports (default: 5)")
     parser.add_argument("--start-at", type=str, default=None,
                        help="Schedule orchestration to start at specific time. Examples: '2h' (2 hours from now), '30m' (30 minutes), '14:30' (2:30 PM today), '1am' (1 AM today/tomorrow)")
-    parser.add_argument("--use-cloud-sql", action="store_true",
-                       help="Save metrics to CloudSQL database (NetraOptimizer integration)")
 
     # Direct command options
     parser.add_argument("--instance-name", type=str, help="Instance name for direct command execution")
@@ -2454,10 +2491,6 @@ async def main():
     
     logger.info(f"Using workspace: {workspace}")
 
-    # Handle CLI extension commands
-    if handle_example_commands and handle_example_commands(args):
-        return
-
 
     # Load instance configurations with direct command precedence
     direct_instance = create_direct_instance(args, workspace)
@@ -2547,7 +2580,6 @@ async def main():
         startup_delay=args.startup_delay,
         max_line_length=args.max_line_length,
         status_report_interval=args.status_report_interval,
-        use_cloud_sql=args.use_cloud_sql,
         quiet=args.quiet,
         overall_token_budget=final_overall_budget,
         overall_cost_budget=final_overall_cost_budget,
@@ -2775,9 +2807,6 @@ async def main():
 
     # Run all instances
     logger.info("Starting Claude Code instance orchestration")
-    if args.use_cloud_sql:
-        logger.info(f"Batch ID: {orchestrator.batch_id}")
-        logger.info("Metrics will be saved to CloudSQL")
     start_time = time.time()
 
     results = await orchestrator.run_all_instances(args.timeout)
@@ -2909,19 +2938,17 @@ async def main():
 
     # For detailed data access
     print("\n" + "="*80)
-    print("🚀 NEED DETAILED TOKEN ANALYTICS & DATA ACCESS?")
+    print("🚀 Looking for more?")
     print("="*80)
-    print("For comprehensive token usage analytics, historical data,")
-    print("and advanced reporting features, upgrade to Netra Apex.")
+    print("Explore Zen with Apex for the most effective AI Ops value for production AI.")
     print("")
     print("🌐 Learn more: https://netrasystems.ai/")
     print("="*80)
 
-    # Show CloudSQL info if enabled
-    if args.use_cloud_sql:
-        print(f"\n📊 Local metrics displayed above")
-        print(f"   Batch ID: {orchestrator.batch_id}")
-        print(f"   Database persistence disabled for security")
+
+    # Flush telemetry before exit
+    if telemetry_manager is not None and hasattr(telemetry_manager, "shutdown"):
+        telemetry_manager.shutdown()
 
     # Exit with appropriate code
     sys.exit(0 if summary['failed'] == 0 else 1)
@@ -2931,4 +2958,4 @@ def run():
     asyncio.run(main())
 
 if __name__ == "__main__":
-    run()
+    run()