@respan/cli 0.10.0 → 0.12.0

package/dist/commands/setup/tracing.d.ts

@@ -0,0 +1,16 @@
+import { SetupBaseCommand } from '../../lib/setup-base-command.js';
+export default class SetupTracing extends SetupBaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        agent: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'no-instrument': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        csv: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/setup/tracing.js

@@ -0,0 +1,33 @@
+import { Flags } from '@oclif/core';
+import { SetupBaseCommand } from '../../lib/setup-base-command.js';
+class SetupTracing extends SetupBaseCommand {
+    async run() {
+        const { flags } = await this.parse(SetupTracing);
+        this.globalFlags = flags;
+        await this.runSetup('tracing', {
+            agent: flags.agent,
+            noInstrument: flags['no-instrument'],
+        });
+    }
+}
+SetupTracing.description = `Set up Respan SDK tracing in this project.
+
+Runs the tracing setup flow directly (skips the "Tracing or Gateway?"
+question). Sets up your API key, installs the Respan skill, and optionally
+opens your coding agent to instrument the project.`;
+SetupTracing.examples = [
+    'respan setup tracing',
+    'respan setup tracing --agent claude-code',
+    'respan setup tracing --no-instrument',
+];
+SetupTracing.flags = {
+    ...SetupBaseCommand.baseFlags,
+    agent: Flags.string({
+        description: 'Agent to configure (claude-code, cursor, codex-cli, gemini-cli, opencode)',
+    }),
+    'no-instrument': Flags.boolean({
+        description: 'Skip opening the agent after setup',
+        default: false,
+    }),
+};
+export default SetupTracing;

package/dist/lib/agents.d.ts

@@ -0,0 +1,16 @@
+export type CliTool = 'claude-code' | 'cursor' | 'codex-cli' | 'gemini-cli' | 'opencode';
+export interface ToolMeta {
+    name: string;
+    binary: string;
+    description: string;
+    configDirs: string[];
+}
+export declare const CLI_TOOLS: Record<CliTool, ToolMeta>;
+export interface DetectionSignal {
+    tool: CliTool;
+    onPath: boolean;
+    hasConfigDir: boolean;
+    reason: string;
+}
+export declare function isBinaryInstalled(binary: string): boolean;
+export declare function detectAgents(projectRoot: string, home: string): DetectionSignal[];

package/dist/lib/agents.js

@@ -0,0 +1,75 @@
+// Coding-agent registry and detection primitives.
+//
+// This is the single source of truth for the agents Respan can configure.
+// commands/setup/index.ts and commands/setup/doctor.ts previously maintained
+// parallel copies of this metadata.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execSync } from 'node:child_process';
+export const CLI_TOOLS = {
+    'claude-code': {
+        name: 'Claude Code',
+        binary: 'claude',
+        description: 'Anthropic\'s coding agent',
+        configDirs: ['~/.claude', '.claude'],
+    },
+    'cursor': {
+        name: 'Cursor',
+        binary: 'cursor',
+        description: 'AI-powered code editor',
+        configDirs: ['.cursor', '.cursorrc'],
+    },
+    'codex-cli': {
+        name: 'Codex CLI',
+        binary: 'codex',
+        description: 'OpenAI\'s coding agent',
+        configDirs: ['~/.codex', '.codex'],
+    },
+    'gemini-cli': {
+        name: 'Gemini CLI',
+        binary: 'gemini',
+        description: 'Google\'s coding agent',
+        configDirs: ['~/.gemini', '.gemini'],
+    },
+    'opencode': {
+        name: 'OpenCode',
+        binary: 'opencode',
+        description: 'Open-source coding agent',
+        configDirs: ['.opencode'],
+    },
+};
+export function isBinaryInstalled(binary) {
+    try {
+        execSync(`command -v ${binary}`, { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function detectAgents(projectRoot, home) {
+    const signals = [];
+    for (const [id, meta] of Object.entries(CLI_TOOLS)) {
+        const onPath = isBinaryInstalled(meta.binary);
+        const hasConfigDir = meta.configDirs.some((dir) => {
+            const resolved = dir.startsWith('~')
+                ? path.join(home, dir.slice(1))
+                : dir.startsWith('.')
+                    ? path.join(projectRoot, dir)
+                    : dir;
+            return fs.existsSync(resolved);
+        });
+        const reasons = [];
+        if (onPath)
+            reasons.push('binary on PATH');
+        if (hasConfigDir)
+            reasons.push('config directory found');
+        signals.push({
+            tool: id,
+            onPath,
+            hasConfigDir,
+            reason: reasons.length > 0 ? reasons.join(', ') : 'not detected',
+        });
+    }
+    return signals;
+}

package/dist/lib/auth.js

@@ -1,4 +1,6 @@
+import * as path from 'node:path';
 import { getCredential } from './config.js';
+import { findProjectRoot, readTextFile, extractEnvVar } from './integrate.js';
 export const DEFAULT_BASE_URL = 'https://api.respan.ai';
 export const ENTERPRISE_BASE_URL = 'https://endpoint.respan.ai';
 function normalizeBaseUrl(baseUrl) {
@@ -9,6 +11,19 @@ function resolveConfiguredBaseUrl(credential, flagBaseUrl) {
     // the main persistent configuration path for CLI users.
     return normalizeBaseUrl(flagBaseUrl || process.env.RESPAN_API_BASE_URL || credential?.baseUrl || DEFAULT_BASE_URL);
 }
+/**
+ * Read RESPAN_API_KEY from the project's `.env`. setup writes it there as the
+ * project source of truth, so in-project commands (e.g. `respan logs list`)
+ * work right after setup without a separate `respan auth login`.
+ */
+function readProjectEnvKey() {
+    try {
+        return extractEnvVar(readTextFile(path.join(findProjectRoot(), '.env')), 'RESPAN_API_KEY');
+    }
+    catch {
+        return undefined;
+    }
+}
 export function resolveAuth(flags) {
     const credential = getCredential(flags.profile);
     const baseUrl = resolveConfiguredBaseUrl(credential, flags['base-url']);
@@ -21,6 +36,15 @@ export function resolveAuth(flags) {
             baseUrl,
         };
     }
+    // The project .env key wins over a saved credential — but an explicit
+    // --profile selects a specific credential (and its base URL), so don't let
+    // an ambient .env key override that choice and break enterprise setups.
+    if (!flags.profile) {
+        const projectEnvKey = readProjectEnvKey();
+        if (projectEnvKey) {
+            return { apiKey: projectEnvKey, baseUrl };
+        }
+    }
     if (credential) {
         return credentialToAuth(credential, baseUrl);
     }

package/dist/lib/colors.d.ts

@@ -0,0 +1,7 @@
+export declare const PC = "\u001B[38;2;100;131;240m";
+export declare const RESET = "\u001B[0m";
+export declare const DIM = "\u001B[2m";
+export declare const GREEN = "\u001B[32m";
+export declare const BOLD = "\u001B[1m";
+export declare const RED = "\u001B[31m";
+export declare const YELLOW = "\u001B[33m";

package/dist/lib/colors.js

@@ -0,0 +1,10 @@
+// Shared ANSI color/style constants for setup-related commands.
+// Consolidated from the copies previously inlined in commands/setup/index.ts
+// and commands/setup/doctor.ts.
+export const PC = '\x1b[38;2;100;131;240m';
+export const RESET = '\x1b[0m';
+export const DIM = '\x1b[2m';
+export const GREEN = '\x1b[32m';
+export const BOLD = '\x1b[1m';
+export const RED = '\x1b[31m';
+export const YELLOW = '\x1b[33m';

package/dist/lib/demo/dataset-fixtures.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Frozen demo datasets for `respan demo`, hand-authored as typed TypeScript.
+ *
+ * Two datasets, numbered to match the demo prompt/evaluator they pair with:
+ *   - "Demo dataset 1: support messages"  -> prompt 1 / evaluator 1
+ *       Rows are customer messages that probe Lumen's refund/escalation policy
+ *       edges. No `expected_output` — evaluator 1 scores compliance from the
+ *       reply alone (it uses {{input}}/{{output}} only).
+ *   - "Demo dataset 3: call transcripts"  -> prompt 3 / evaluator 3
+ *       Rows are call transcripts, each with a gold-label classification in
+ *       `expected_output` (evaluator 3 compares against {{expected_output}}).
+ *
+ * `input` is an object of the prompt's template variables (`customer_message` /
+ * `call_transcript`); it is stored stringified and parsed into the row's mapped
+ * fields. `expected_output` is authored here as an object for readability and
+ * JSON-stringified at seed time — passing a raw object makes the platform coerce
+ * it to single-quoted python-repr (invalid JSON the grader would then see).
+ */
+/** One dataset row: template variables plus an optional gold label. */
+export interface DemoDatasetRow {
+    /** The prompt's template variables for this row. */
+    input: Record<string, unknown>;
+    /** Gold label (object; stringified to JSON at seed time). */
+    expected_output?: unknown;
+}
+/** One demo dataset: name/description plus its rows. */
+export interface DemoDatasetFixture {
+    name: string;
+    description?: string;
+    rows: DemoDatasetRow[];
+}
+export declare const DEMO_DATASETS: DemoDatasetFixture[];

package/dist/lib/demo/dataset-fixtures.js

@@ -0,0 +1,194 @@
+/**
+ * Frozen demo datasets for `respan demo`, hand-authored as typed TypeScript.
+ *
+ * Two datasets, numbered to match the demo prompt/evaluator they pair with:
+ *   - "Demo dataset 1: support messages"  -> prompt 1 / evaluator 1
+ *       Rows are customer messages that probe Lumen's refund/escalation policy
+ *       edges. No `expected_output` — evaluator 1 scores compliance from the
+ *       reply alone (it uses {{input}}/{{output}} only).
+ *   - "Demo dataset 3: call transcripts"  -> prompt 3 / evaluator 3
+ *       Rows are call transcripts, each with a gold-label classification in
+ *       `expected_output` (evaluator 3 compares against {{expected_output}}).
+ *
+ * `input` is an object of the prompt's template variables (`customer_message` /
+ * `call_transcript`); it is stored stringified and parsed into the row's mapped
+ * fields. `expected_output` is authored here as an object for readability and
+ * JSON-stringified at seed time — passing a raw object makes the platform coerce
+ * it to single-quoted python-repr (invalid JSON the grader would then see).
+ */
+export const DEMO_DATASETS = [
+    {
+        name: 'Demo dataset 1: support messages',
+        description: 'Customer messages that probe Lumen Electronics refund/escalation policy edges, for evaluating the support agent (prompt 1).',
+        rows: [
+            {
+                input: {
+                    customer_message: "Hi, my wireless earbuds (order A-50231) arrived two days ago but the left one won't charge. I'd like a refund, please.",
+                },
+            },
+            {
+                input: {
+                    customer_message: "I bought the clearance Lumen soundbar (order A-49120, it was marked final sale) last week and I've changed my mind. I'd like my money back.",
+                },
+            },
+            {
+                input: {
+                    customer_message: "Order A-51002 was supposed to arrive yesterday and it's still not here. I want a refund for the delay.",
+                },
+            },
+            {
+                input: {
+                    customer_message: 'Tracking says my package (A-48817) was delivered three days ago, but I never received it. I want a full refund.',
+                },
+            },
+            {
+                input: {
+                    customer_message: 'Please process a refund on order A-52340 for $349.99.',
+                },
+            },
+            {
+                input: {
+                    customer_message: "My Lumen 4K monitor (order A-53001) stopped working after two days — it was $279. I'd like a refund because it's defective.",
+                },
+            },
+            {
+                input: {
+                    customer_message: "Where is my order A-50777? I just want to know when it'll arrive.",
+                },
+            },
+        ],
+    },
+    {
+        name: 'Demo dataset 3: call transcripts',
+        description: 'Support call transcripts with gold-label classifications, for evaluating the call-transcript classifier (prompt 3).',
+        rows: [
+            {
+                input: {
+                    call_transcript: 'Agent: Hi, this is Dana at Lumen Electronics support. How can I help you today?\n' +
+                        "Customer: My monitor, order A-51440, arrived with a cracked panel. I'm pretty annoyed.\n" +
+                        "Agent: I'm really sorry about that. I've created a replacement order — it ships today and you'll get tracking by email.\n" +
+                        'Customer: Oh, great. Thank you, that was easy.\n' +
+                        'Agent: My pleasure. Have a great day.',
+                },
+                expected_output: {
+                    primary_reason: 'product_defect',
+                    resolution_status: 'resolved',
+                    customer_sentiment_start: 'frustrated',
+                    customer_sentiment_end: 'positive',
+                    escalation_requested: false,
+                    followup_required: true,
+                    order_ids: ['A-51440'],
+                    products_mentioned: ['Lumen Monitor'],
+                    agent_name: 'Dana',
+                    summary: 'Customer reported a cracked monitor panel (A-51440); agent created a same-day replacement shipment.',
+                    key_quote: 'My monitor, order A-51440, arrived with a cracked panel.',
+                    agent_followed_greeting: true,
+                    agent_empathy_shown: true,
+                    compliance_flags: [],
+                },
+            },
+            {
+                input: {
+                    call_transcript: 'Agent: Thanks for calling Lumen Electronics, this is Marcus.\n' +
+                        "Customer: I was charged twice for order A-52210 and nobody's fixed it. I want a manager, now.\n" +
+                        "Agent: I can see two charges. I'm not able to reverse it from my side today.\n" +
+                        "Customer: Unacceptable. Escalate this or I'm calling my bank for a chargeback.\n" +
+                        "Agent: I'll escalate to a supervisor who will call you back within 24 hours.\n" +
+                        'Customer: Fine.',
+                },
+                expected_output: {
+                    primary_reason: 'billing_dispute',
+                    resolution_status: 'escalated',
+                    customer_sentiment_start: 'angry',
+                    customer_sentiment_end: 'frustrated',
+                    escalation_requested: true,
+                    followup_required: true,
+                    order_ids: ['A-52210'],
+                    products_mentioned: [],
+                    agent_name: 'Marcus',
+                    summary: 'Customer disputed a double charge on A-52210 and demanded a manager; agent escalated to a supervisor with a 24-hour callback.',
+                    key_quote: "I was charged twice for order A-52210 and nobody's fixed it.",
+                    agent_followed_greeting: true,
+                    agent_empathy_shown: false,
+                    compliance_flags: ['no_identity_verification'],
+                },
+            },
+            {
+                input: {
+                    call_transcript: 'Agent: Hi, my name is Max and this is the customer support line for Lumen Electronics. How can I help you today?\n' +
+                        'Customer: Finally. I ordered the Lumen Wireless Headphones almost two weeks ago, order A-48217, and they still have not shown up. This is ridiculous.\n' +
+                        "Agent: I'm really sorry about the wait, and I understand how frustrating that is. It looks like A-48217 was delayed at the carrier's sorting facility. I've flagged it and I'll email you an update within 24 hours.\n" +
+                        "Customer: Okay, I'd appreciate that.\n" +
+                        'Agent: Thank you for your patience.',
+                },
+                expected_output: {
+                    primary_reason: 'shipping_delay',
+                    resolution_status: 'partially_resolved',
+                    customer_sentiment_start: 'frustrated',
+                    customer_sentiment_end: 'neutral',
+                    escalation_requested: false,
+                    followup_required: true,
+                    order_ids: ['A-48217'],
+                    products_mentioned: ['Lumen Wireless Headphones'],
+                    agent_name: 'Max',
+                    summary: 'Customer reported headphones order A-48217 was delayed; agent identified a carrier delay and promised an emailed update within 24 hours.',
+                    key_quote: 'I ordered the Lumen Wireless Headphones almost two weeks ago and they still have not shown up.',
+                    agent_followed_greeting: true,
+                    agent_empathy_shown: true,
+                    compliance_flags: [],
+                },
+            },
+            {
+                input: {
+                    call_transcript: "Agent: Hello, you've reached Lumen Electronics, this is Priya.\n" +
+                        "Customer: Hi, I'd like to return my speaker, order A-50988. It works fine, I just don't need it.\n" +
+                        'Agent: No problem. It is within our 30-day window, so I have issued a full refund of $59.99 and emailed a prepaid return label.\n' +
+                        'Customer: Perfect, thanks so much.\n' +
+                        "Agent: You're welcome!",
+                },
+                expected_output: {
+                    primary_reason: 'return_or_refund',
+                    resolution_status: 'resolved',
+                    customer_sentiment_start: 'neutral',
+                    customer_sentiment_end: 'positive',
+                    escalation_requested: false,
+                    followup_required: true,
+                    order_ids: ['A-50988'],
+                    products_mentioned: ['Lumen Speaker'],
+                    agent_name: 'Priya',
+                    summary: 'Customer requested a return for unwanted speaker A-50988; agent issued a full refund and sent a prepaid return label.',
+                    key_quote: "I'd like to return my speaker, order A-50988. It works fine, I just don't need it.",
+                    agent_followed_greeting: true,
+                    agent_empathy_shown: false,
+                    compliance_flags: [],
+                },
+            },
+            {
+                input: {
+                    call_transcript: "Customer: My Lumen smart hub won't connect to wifi no matter what I try.\n" +
+                        'Agent: Have you tried resetting it? Hold the button for ten seconds.\n' +
+                        'Customer: Yes, three times. Still nothing.\n' +
+                        "Agent: I'm not sure what else to suggest. I'll open a ticket and someone from tech will email you.\n" +
+                        'Customer: So you can’t actually help me right now?\n' +
+                        'Agent: Not today, sorry.',
+                },
+                expected_output: {
+                    primary_reason: 'technical_support',
+                    resolution_status: 'unresolved',
+                    customer_sentiment_start: 'frustrated',
+                    customer_sentiment_end: 'frustrated',
+                    escalation_requested: false,
+                    followup_required: true,
+                    order_ids: [],
+                    products_mentioned: ['Lumen Smart Hub'],
+                    agent_name: null,
+                    summary: 'Customer’s smart hub would not connect to wifi; a basic reset failed and the agent opened a ticket for tech to follow up by email.',
+                    key_quote: "My Lumen smart hub won't connect to wifi no matter what I try.",
+                    agent_followed_greeting: false,
+                    agent_empathy_shown: false,
+                    compliance_flags: ['no_identity_verification', 'no_resolution_offered'],
+                },
+            },
+        ],
+    },
+];

package/dist/lib/demo/evaluator-fixtures.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Frozen snapshot of the demo evaluators, captured byte-for-byte from the
+ * owner's deployed evaluators (graders + Blockly workflow task graphs).
+ *
+ * Source of truth for `respan demo`. Each entry is one user-facing evaluator: the
+ * deployed workflow's task graph plus the grader record(s) it references. The
+ * grader `type` is captured verbatim ("human" is the stored default) — the actual
+ * LLM engine lives in each eval task's `generation_method`/`_blockly_evaluator_kind`,
+ * so replaying the graph reproduces the verified scoring behavior exactly.
+ *
+ * This is a frozen snapshot: if the source evaluators change, this file does NOT
+ * update until someone re-snapshots and ships a new build.
+ *
+ * Recreate recipe (see seed-evaluators.ts): create each grader -> map its
+ * `originalId` to the new id -> rewrite every eval task's `config.evaluator_id`
+ * via that map -> createWorkflow -> commit -> deploy. Task ids are kept verbatim
+ * so the compute task's `state.<task_id>` input references stay valid.
+ */
+/** A grader record referenced by an evaluator's workflow. */
+export interface DemoEvaluatorGrader {
+    name: string;
+    /** The grader's id inside the captured task graph. Remapped to the freshly
+     * created grader id at seed time so the eval tasks point at the new record. */
+    originalId: string;
+    type: string;
+    score_value_type: string;
+    score_config: Record<string, unknown>;
+    passing_conditions: Record<string, unknown>;
+    llm_config: Record<string, unknown>;
+}
+/** One demo evaluator: the deployed workflow graph plus its grader(s). */
+export interface DemoEvaluatorFixture {
+    /** Workflow name (the user-facing evaluator name); used for dedup. */
+    workflowName: string;
+    description?: string;
+    graders: DemoEvaluatorGrader[];
+    /** Verbatim deployed workflow task graph. Only each eval task's
+     * `config.evaluator_id` is rewritten at seed time. */
+    tasks: Record<string, unknown>[];
+}
+export declare const DEMO_EVALUATORS: DemoEvaluatorFixture[];