@respan/cli 0.5.1 → 0.5.3

package/dist/assets/hook.py

@@ -492,6 +492,7 @@ def create_respan_spans(
         "span_name": root_span_name,
         "span_workflow_name": workflow_name,
         "model": model,
+        "provider_id": "",
         "span_path": "",
         "input": json.dumps(prompt_messages) if prompt_messages else "",
         "output": json.dumps(completion_message) if completion_message else "",
@@ -524,6 +525,7 @@ def create_respan_spans(
         "span_path": "claude_chat",
         "model": model,
         "provider_id": "anthropic",
+        "metadata": {},
         "input": json.dumps(prompt_messages) if prompt_messages else "",
         "output": json.dumps(completion_message) if completion_message else "",
         "prompt_messages": prompt_messages,
@@ -560,6 +562,8 @@ def create_respan_spans(
                     "span_name": f"Thinking {thinking_num}",
                     "span_workflow_name": workflow_name,
                     "span_path": "thinking",
+                    "provider_id": "",
+                    "metadata": {},
                     "input": "",
                     "output": thinking_text,
                     "timestamp": thinking_ts,
@@ -610,13 +614,14 @@ def create_respan_spans(
             "span_name": f"Tool: {td['name']}",
             "span_workflow_name": workflow_name,
             "span_path": f"tool_{td['name'].lower()}",
+            "provider_id": "",
+            "metadata": td.get("result_metadata") or {},
             "input": format_tool_input(td["name"], td["input"]),
             "output": format_tool_output(td["name"], td.get("output")),
             "timestamp": tool_ts,
             "start_time": tool_start,
         }
         if td.get("result_metadata"):
-            tool_span["metadata"] = td["result_metadata"]
             duration_ms = td["result_metadata"].get("duration_ms")
             if duration_ms:
                 tool_span["latency"] = duration_ms / 1000.0
@@ -937,17 +942,17 @@ def main():
         debug("Tracing disabled (TRACE_TO_RESPAN != true)")
         sys.exit(0)
 
-    # Resolve API key: env var > ~/.config/respan/credentials.json
+    # Resolve API key: env var > ~/.respan/credentials.json
     api_key = os.getenv("RESPAN_API_KEY")
     base_url = os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api")
 
     if not api_key:
-        creds_file = Path.home() / ".config" / "respan" / "credentials.json"
+        creds_file = Path.home() / ".respan" / "credentials.json"
         if creds_file.exists():
             try:
                 creds = json.loads(creds_file.read_text(encoding="utf-8"))
                 # Find the active profile's credential
-                config_file = Path.home() / ".config" / "respan" / "config.json"
+                config_file = Path.home() / ".respan" / "config.json"
                 profile = "default"
                 if config_file.exists():
                     cfg = json.loads(config_file.read_text(encoding="utf-8"))
@@ -956,6 +961,9 @@ def main():
                 api_key = cred.get("apiKey") or cred.get("accessToken")
                 if not base_url or base_url == "https://api.respan.ai/api":
                     base_url = cred.get("baseUrl", base_url)
+                # Ensure base_url ends with /api (credentials store the host only)
+                if base_url and not base_url.rstrip("/").endswith("/api"):
+                    base_url = base_url.rstrip("/") + "/api"
                 if api_key:
                     debug(f"Using API key from credentials.json (profile: {profile})")
             except (json.JSONDecodeError, IOError) as e:

package/dist/commands/integrate/claude-code.js

@@ -7,7 +7,7 @@ class IntegrateClaudeCode extends BaseCommand {
         const { flags } = await this.parse(IntegrateClaudeCode);
         this.globalFlags = flags;
         try {
-            // Verify the user is authenticated (key is read by hook from ~/.config/respan/)
+            // Verify the user is authenticated (key is read by hook from ~/.respan/)
             this.resolveApiKey();
             const baseUrl = flags['base-url'];
             const projectId = flags['project-id'];
@@ -93,7 +93,7 @@ class IntegrateClaudeCode extends BaseCommand {
                 const projectRoot = findProjectRoot();
                 const localSettingsPath = `${projectRoot}/.claude/settings.local.json`;
                 const localSettings = readJsonFile(localSettingsPath);
-                // settings.local.json: enable flag only (API key from ~/.config/respan/)
+                // settings.local.json: enable flag only (API key from ~/.respan/)
                 const envBlock = {
                     TRACE_TO_RESPAN: 'true',
                 };
@@ -150,7 +150,7 @@ class IntegrateClaudeCode extends BaseCommand {
                 this.log('Claude Code tracing enabled for this project.');
             }
             this.log('');
-            this.log('Auth:   ~/.config/respan/credentials.json  (from `respan auth login`)');
+            this.log('Auth:   ~/.respan/credentials.json  (from `respan auth login`)');
             this.log('Config: .claude/respan.json                (shareable, non-secret)');
             this.log('');
             this.log('Set properties via integrate flags or edit .claude/respan.json:');

package/dist/commands/integrate/codex-cli.d.ts

@@ -19,5 +19,13 @@ export default class IntegrateCodexCli extends BaseCommand {
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    /**
+     * Update or insert the `notify` line in a TOML config string.
+     *
+     * TOML bare keys must appear before the first [table] header.
+     * If a `notify` line already exists, replace it in-place.
+     * Otherwise, insert the notify line before the first [table] header.
+     */
+    private updateTomlNotify;
     private resolveApiKey;
 }

package/dist/commands/integrate/codex-cli.js

@@ -1,69 +1,161 @@
-import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { execSync } from 'node:child_process';
 import { BaseCommand } from '../../lib/base-command.js';
-import { integrateFlags, readTextFile, writeTextFile, expandHome, parseAttrs, toOtelResourceAttrs, resolveScope, findProjectRoot, } from '../../lib/integrate.js';
+import { integrateFlags, readTextFile, writeTextFile, writeJsonFile, readJsonFile, expandHome, parseAttrs, getCodexHookScript, resolveScope, findProjectRoot, } from '../../lib/integrate.js';
 class IntegrateCodexCli extends BaseCommand {
     async run() {
         const { flags } = await this.parse(IntegrateCodexCli);
         this.globalFlags = flags;
         try {
-            const apiKey = this.resolveApiKey();
-            const baseUrl = (flags['base-url']).replace(/\/+$/, '');
+            // Verify the user is authenticated (key is read by hook from ~/.respan/)
+            this.resolveApiKey();
             const projectId = flags['project-id'];
+            const customerId = flags['customer-id'];
+            const spanName = flags['span-name'];
+            const workflowName = flags['workflow-name'];
             const attrs = parseAttrs(flags.attrs);
             const dryRun = flags['dry-run'];
-            const scope = resolveScope(flags, 'local');
-            // Resolve target config file
-            const configPath = scope === 'global'
-                ? expandHome('~/.codex/config.toml')
-                : path.join(findProjectRoot(), '.codex', 'config.toml');
-            const existing = readTextFile(configPath);
-            // Check for existing [otel] block
-            if (/^\[otel\]/m.test(existing)) {
-                this.warn(`[otel] section already exists in ${configPath} — skipping to avoid overwrite.`);
-                this.warn('Remove or rename the existing [otel] section and re-run to update.');
-                return;
+            // Codex CLI default: both global + local
+            const scope = resolveScope(flags, 'both');
+            const doGlobal = scope === 'global' || scope === 'both';
+            const doLocal = scope === 'local' || scope === 'both';
+            // ── Global: hook script + notify registration ──────────────────
+            if (doGlobal) {
+                // 1. Ensure Python 'requests' is available
+                if (!dryRun) {
+                    try {
+                        execSync('python3 -c "import requests"', { stdio: 'pipe' });
+                    }
+                    catch {
+                        this.log('Installing Python requests package...');
+                        try {
+                            execSync('pip3 install requests', { stdio: 'pipe' });
+                            this.log('Installed requests.');
+                        }
+                        catch {
+                            this.warn('Could not install Python requests package automatically.\n' +
+                                'Install it manually: pip3 install requests');
+                        }
+                    }
+                }
+                else {
+                    this.log('[dry-run] Would verify Python requests package');
+                }
+                // 2. Write hook script
+                const hookPath = expandHome('~/.respan/codex_hook.py');
+                if (dryRun) {
+                    this.log(`[dry-run] Would write hook script to: ${hookPath}`);
+                }
+                else {
+                    writeTextFile(hookPath, getCodexHookScript());
+                    fs.chmodSync(hookPath, 0o755);
+                    this.log(`Wrote hook script: ${hookPath}`);
+                }
+                // 3. Register notify hook in ~/.codex/config.toml
+                const configPath = expandHome('~/.codex/config.toml');
+                const existing = readTextFile(configPath);
+                const notifyValue = `notify = ["python3", "${hookPath}"]`;
+                const updated = this.updateTomlNotify(existing, notifyValue);
+                if (dryRun) {
+                    this.log(`[dry-run] Would update: ${configPath}`);
+                    this.log(updated);
+                }
+                else {
+                    writeTextFile(configPath, updated);
+                    this.log(`Updated config: ${configPath}`);
+                }
             }
-            // Build resource attributes
-            const resourceAttrs = {
-                'service.name': 'codex-cli',
-                ...attrs,
-            };
-            if (projectId) {
-                resourceAttrs['respan.project_id'] = projectId;
+            // ── Local: .codex/respan.json ──────────────────────────────────
+            if (doLocal) {
+                const projectRoot = findProjectRoot();
+                const respanConfigPath = `${projectRoot}/.codex/respan.json`;
+                const respanConfig = readJsonFile(respanConfigPath);
+                const newConfig = { ...respanConfig };
+                if (customerId) {
+                    newConfig.customer_id = customerId;
+                }
+                if (spanName) {
+                    newConfig.span_name = spanName;
+                }
+                if (workflowName) {
+                    newConfig.workflow_name = workflowName;
+                }
+                if (projectId) {
+                    newConfig.project_id = projectId;
+                }
+                // Custom attrs go as top-level keys (unknown keys = custom properties)
+                for (const [k, v] of Object.entries(attrs)) {
+                    newConfig[k] = v;
+                }
+                if (Object.keys(newConfig).length > 0) {
+                    if (dryRun) {
+                        this.log(`[dry-run] Would write: ${respanConfigPath}`);
+                        this.log(JSON.stringify(newConfig, null, 2));
+                    }
+                    else {
+                        writeJsonFile(respanConfigPath, newConfig);
+                        this.log(`Wrote Respan config: ${respanConfigPath}`);
+                    }
+                }
             }
-            const otelResStr = toOtelResourceAttrs(resourceAttrs);
-            // Build TOML block
-            const lines = [
-                '',
-                '# Respan observability (added by respan integrate codex-cli)',
-                '[otel]',
-                `endpoint = "${baseUrl}/v2/traces"`,
-                `api_key = "${apiKey}"`,
-            ];
-            if (otelResStr) {
-                lines.push(`resource_attributes = "${otelResStr}"`);
+            // ── Done ────────────────────────────────────────────────────────
+            this.log('');
+            if (doGlobal && doLocal) {
+                this.log('Codex CLI integration complete (global hook + project config).');
             }
-            lines.push('');
-            const block = lines.join('\n');
-            const updated = existing.trimEnd() + '\n' + block;
-            if (dryRun) {
-                this.log(`[dry-run] Would append to: ${configPath}`);
-                this.log(block);
+            else if (doGlobal) {
+                this.log('Codex CLI global hook installed.');
+                this.log('Run without --global in a project to configure tracing there.');
             }
             else {
-                writeTextFile(configPath, updated);
-                this.log(`Updated config: ${configPath}`);
+                this.log('Codex CLI tracing configured for this project.');
             }
             this.log('');
-            this.log(`Codex CLI integration complete (${scope}).`);
+            this.log('Auth:   ~/.respan/credentials.json  (from `respan auth login`)');
+            this.log('Config: .codex/respan.json                 (shareable, non-secret)');
+            this.log('');
+            this.log('Set properties via integrate flags or edit .codex/respan.json:');
+            this.log('  respan integrate codex-cli --customer-id "frank" --span-name "my-app"');
+            this.log('  respan integrate codex-cli --attrs \'{"team":"platform","env":"staging"}\'');
             this.log('');
-            this.log('Set dynamic attributes before a session:');
-            this.log('  export OTEL_RESOURCE_ATTRIBUTES="env=prod,task_id=T-123"');
+            this.log('Override per-session with env vars:');
+            this.log('  export RESPAN_CUSTOMER_ID="your-name"');
+            this.log("  export RESPAN_METADATA='{\"task_id\":\"T-123\"}'");
+            this.log('');
+            this.log('Debug: CODEX_RESPAN_DEBUG=true → check ~/.codex/state/respan_hook.log');
         }
         catch (error) {
             this.handleError(error);
         }
     }
+    /**
+     * Update or insert the `notify` line in a TOML config string.
+     *
+     * TOML bare keys must appear before the first [table] header.
+     * If a `notify` line already exists, replace it in-place.
+     * Otherwise, insert the notify line before the first [table] header.
+     */
+    updateTomlNotify(existing, notifyValue) {
+        const lines = existing.split('\n');
+        // Check if notify line already exists
+        const notifyIdx = lines.findIndex((line) => /^\s*notify\s*=/.test(line));
+        if (notifyIdx >= 0) {
+            // Replace existing notify line
+            lines[notifyIdx] = notifyValue;
+            return lines.join('\n');
+        }
+        // Find the first [table] header to insert before it
+        const firstTableIdx = lines.findIndex((line) => /^\s*\[/.test(line));
+        if (firstTableIdx >= 0) {
+            // Insert notify + comment before the first table header
+            lines.splice(firstTableIdx, 0, '# Respan observability (added by respan integrate codex-cli)', notifyValue, '');
+        }
+        else {
+            // No tables at all — append to end
+            lines.push('', '# Respan observability (added by respan integrate codex-cli)', notifyValue);
+        }
+        return lines.join('\n');
+    }
     resolveApiKey() {
         const auth = this.getAuth();
         if (auth.apiKey)
@@ -77,17 +169,18 @@ class IntegrateCodexCli extends BaseCommand {
 }
 IntegrateCodexCli.description = `Integrate Respan with Codex CLI.
 
-Codex CLI has native OTel traces (prompts, tool approvals, results)
-so we append an [otel] block to its TOML config.
+Installs a notify hook that reads session JSONL files and sends
+them to Respan as structured spans (chat, tool, reasoning).
 
 Scope:
-  --local    Write to .codex/config.toml in project root (default)
-  --global   Write to ~/.codex/config.toml
-  If [otel] already exists in the target file, warns and does not overwrite.`;
+  --global   Install hook script + register notify in ~/.codex/config.toml
+  --local    Write .codex/respan.json with customer_id, span_name, etc.
+  (default)  Both: install hook globally + config for current project`;
 IntegrateCodexCli.examples = [
     'respan integrate codex-cli',
     'respan integrate codex-cli --global',
-    'respan integrate codex-cli --project-id my-project --attrs \'{"env":"prod"}\'',
+    'respan integrate codex-cli --local --customer-id frank',
+    'respan integrate codex-cli --attrs \'{"env":"prod"}\'',
     'respan integrate codex-cli --dry-run',
 ];
 IntegrateCodexCli.flags = {

package/dist/commands/integrate/gemini-cli.js

@@ -1,6 +1,6 @@
 import * as path from 'node:path';
 import { BaseCommand } from '../../lib/base-command.js';
-import { integrateFlags, deepMerge, readJsonFile, writeJsonFile, expandHome, parseAttrs, toOtelResourceAttrs, resolveScope, findProjectRoot, } from '../../lib/integrate.js';
+import { integrateFlags, deepMerge, readJsonFile, writeJsonFile, readTextFile, writeTextFile, expandHome, parseAttrs, toOtelResourceAttrs, resolveScope, findProjectRoot, } from '../../lib/integrate.js';
 class IntegrateGeminiCli extends BaseCommand {
     async run() {
         const { flags } = await this.parse(IntegrateGeminiCli);
@@ -25,27 +25,48 @@ class IntegrateGeminiCli extends BaseCommand {
             if (projectId) {
                 resourceAttrs['respan.project_id'] = projectId;
             }
+            // settings.json — only telemetry fields Gemini CLI supports
             const patch = {
                 telemetry: {
                     enabled: true,
                     otlpEndpoint: `${baseUrl}/v2/traces`,
-                    headers: {
-                        Authorization: `Bearer ${apiKey}`,
-                    },
+                    otlpProtocol: 'http',
                 },
             };
+            const merged = deepMerge(existing, patch);
+            // .env file — OTel SDK picks up headers & resource attrs from env
+            const envDir = scope === 'global'
+                ? expandHome('~/.gemini')
+                : path.join(findProjectRoot(), '.gemini');
+            const envPath = path.join(envDir, '.env');
+            const envLines = [];
+            envLines.push(`OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer ${apiKey}`);
             const otelResStr = toOtelResourceAttrs(resourceAttrs);
             if (otelResStr) {
-                patch.env = { OTEL_RESOURCE_ATTRIBUTES: otelResStr };
+                envLines.push(`OTEL_RESOURCE_ATTRIBUTES=${otelResStr}`);
             }
-            const merged = deepMerge(existing, patch);
+            // Merge with existing .env (replace our keys, keep the rest)
+            const existingEnv = readTextFile(envPath);
+            const envKeysToSet = new Set(envLines.map(l => l.split('=')[0]));
+            const keptLines = existingEnv
+                .split('\n')
+                .filter(line => {
+                const key = line.split('=')[0];
+                return !envKeysToSet.has(key);
+            });
+            const finalEnv = [...keptLines.filter(l => l.trim() !== ''), ...envLines].join('\n') + '\n';
             if (dryRun) {
                 this.log(`[dry-run] Would update: ${settingsPath}`);
                 this.log(JSON.stringify(merged, null, 2));
+                this.log('');
+                this.log(`[dry-run] Would update: ${envPath}`);
+                this.log(finalEnv);
             }
             else {
                 writeJsonFile(settingsPath, merged);
                 this.log(`Updated settings: ${settingsPath}`);
+                writeTextFile(envPath, finalEnv);
+                this.log(`Updated env: ${envPath}`);
             }
             this.log('');
             this.log(`Gemini CLI integration complete (${scope}).`);

package/dist/lib/config.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-const CONFIG_DIR = path.join(os.homedir(), '.config', 'respan');
+const CONFIG_DIR = path.join(os.homedir(), '.respan');
 const CREDENTIALS_FILE = path.join(CONFIG_DIR, 'credentials.json');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 function ensureConfigDir() {

package/dist/lib/integrate.d.ts

@@ -35,6 +35,10 @@ export declare function findProjectRoot(): string;
  * version — upgrading the CLI and re-running integrate updates the hook.
  */
 export declare function getHookScript(): string;
+/**
+ * Return the bundled Codex CLI hook script contents.
+ */
+export declare function getCodexHookScript(): string;
 /**
  * Deep merge source into target.
  * Objects are recursively merged; arrays and primitives from source overwrite.

package/dist/lib/integrate.js

@@ -87,6 +87,14 @@ export function getHookScript() {
     const hookPath = path.join(dir, '..', 'assets', 'hook.py');
     return fs.readFileSync(hookPath, 'utf-8');
 }
+/**
+ * Return the bundled Codex CLI hook script contents.
+ */
+export function getCodexHookScript() {
+    const dir = path.dirname(fileURLToPath(import.meta.url));
+    const hookPath = path.join(dir, '..', 'assets', 'codex_hook.py');
+    return fs.readFileSync(hookPath, 'utf-8');
+}
 // ── Utilities ─────────────────────────────────────────────────────────────
 /**
  * Deep merge source into target.