@kontourai/flow-agents 0.1.1

package/build/src/cli/telemetry-doctor.js

@@ -0,0 +1,221 @@
+import * as fs from "node:fs";
+import * as http from "node:http";
+import * as https from "node:https";
+import * as path from "node:path";
+import { parseArgs, flagBool, flagString } from "../lib/args.js";
+const defaultChannels = "full";
+const sensitiveQueryKeys = new Set(["token", "api_key", "apikey", "key", "secret", "password", "auth", "authorization", "access_token"]);
+function usage() {
+    console.error(`usage: flow-agents telemetry-doctor [options]
+
+Options:
+  --dest PATH       Installed Flow Agents root. Defaults to current directory.
+  --json           Emit machine-readable JSON.
+  --headless       Do not prompt; suitable for CI.
+  --timeout-ms N   Console reachability timeout. Defaults to 2000.
+  --allow-network  Allow reachability checks to non-local HTTPS Console hosts.
+`);
+}
+function readConfig(file) {
+    if (!fs.existsSync(file))
+        return {};
+    const config = {};
+    for (const line of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = trimmed.slice(0, eq).trim();
+        const value = trimmed.slice(eq + 1).trim();
+        if (key)
+            config[key] = value;
+    }
+    return config;
+}
+function configValue(config, envName, key, fallback = "") {
+    return process.env[envName] ?? config[key] ?? fallback;
+}
+function channelEnvName(channel, key) {
+    return `TELEMETRY_CHANNEL_${channel.toUpperCase()}_${key.toUpperCase()}`;
+}
+function channelConfigValue(config, channel, key, fallback = "") {
+    const envName = channelEnvName(channel, key);
+    return process.env[envName] ?? config[`channel.${channel}.${key}`] ?? fallback;
+}
+function telemetryDataDir(dest) {
+    const configured = process.env.TELEMETRY_DATA_DIR;
+    return configured ? path.resolve(dest, configured) : path.resolve(dest, "..", ".telemetry");
+}
+function deriveConsoleEndpoint(consoleUrl, explicitEndpoint) {
+    if (explicitEndpoint)
+        return explicitEndpoint;
+    if (!consoleUrl)
+        return "";
+    const base = consoleUrl.replace(/\/+$/, "");
+    if (base.endsWith("/api/telemetry/records"))
+        return base;
+    if (base.endsWith("/api/telemetry"))
+        return `${base}/records`;
+    return `${base}/api/telemetry/records`;
+}
+function endpointAllowed(endpointUrl, allowNetwork = false) {
+    if (!endpointUrl || endpointUrl.includes("\n") || endpointUrl.includes("\r") || endpointUrl.includes('"'))
+        return false;
+    const url = parseUrl(endpointUrl);
+    if (!url)
+        return false;
+    if (url.username || url.password)
+        return false;
+    if (url.protocol === "https:")
+        return allowNetwork || isLocalHostname(url.hostname);
+    return url.protocol === "http:" && isLocalHostname(url.hostname);
+}
+function activeSinks(enabled, channels, consoleEndpoint, allowed) {
+    const sinks = [];
+    if (enabled && channels.some((channel) => channel.active && channel.logFile))
+        sinks.push("local-files");
+    if (enabled && channels.some((channel) => channel.active && channel.endpointUrl))
+        sinks.push("channel-endpoint");
+    if (enabled && consoleEndpoint && allowed)
+        sinks.push("console");
+    return sinks;
+}
+function checkConsoleReachability(endpointUrl, timeoutMs, allowNetwork) {
+    if (!endpointUrl)
+        return Promise.resolve({ checked: false, ok: null });
+    if (!endpointAllowed(endpointUrl, allowNetwork))
+        return Promise.resolve({ checked: false, ok: null, error: "endpoint is not allowed" });
+    const url = parseUrl(endpointUrl);
+    if (!url)
+        return Promise.resolve({ checked: false, ok: null, error: "endpoint URL is malformed" });
+    return new Promise((resolve) => {
+        let settled = false;
+        const client = url.protocol === "https:" ? https : http;
+        const req = client.request(url, { method: "HEAD", timeout: timeoutMs }, (res) => {
+            settled = true;
+            res.resume();
+            resolve({ checked: true, ok: Boolean(res.statusCode && res.statusCode < 500), statusCode: res.statusCode });
+        });
+        req.on("timeout", () => {
+            if (settled)
+                return;
+            settled = true;
+            req.destroy();
+            resolve({ checked: true, ok: false, error: `timeout after ${timeoutMs}ms` });
+        });
+        req.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve({ checked: true, ok: false, error: error.message });
+        });
+        req.end();
+    });
+}
+function parseUrl(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
+}
+function isLocalHostname(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname.endsWith(".localhost");
+}
+function safeReportUrl(value) {
+    if (!value)
+        return undefined;
+    const parsed = parseUrl(value);
+    if (!parsed)
+        return "[malformed-url]";
+    parsed.username = "";
+    parsed.password = "";
+    for (const key of Array.from(parsed.searchParams.keys())) {
+        if (sensitiveQueryKeys.has(key.toLowerCase()))
+            parsed.searchParams.set(key, "[redacted]");
+    }
+    return parsed.toString();
+}
+async function buildReport(argv) {
+    const args = parseArgs(argv);
+    const allowNetwork = flagBool(args.flags, "allow-network");
+    const dest = path.resolve(flagString(args.flags, "dest", process.cwd()) ?? process.cwd());
+    const telemetryDir = path.join(dest, "scripts", "telemetry");
+    const configFile = path.join(telemetryDir, "telemetry.conf");
+    const config = readConfig(configFile);
+    const enabled = configValue(config, "TELEMETRY_ENABLED", "enabled", "true") !== "false";
+    const dataDir = telemetryDataDir(dest);
+    const sessionDir = path.resolve(configValue(config, "TELEMETRY_SESSION_DIR", "telemetry_session_dir", path.join(dataDir, "sessions")));
+    const channels = configValue(config, "TELEMETRY_CHANNELS", "channels", defaultChannels).split(",").map((channel) => channel.trim()).filter(Boolean);
+    const channelReports = channels.map((name) => {
+        const defaultLog = name === "full" ? path.join(dataDir, "full.jsonl") : name === "analytics" ? path.join(dataDir, "analytics.jsonl") : "";
+        const logFile = channelConfigValue(config, name, "log_file", defaultLog);
+        const endpointUrl = channelConfigValue(config, name, "endpoint_url");
+        return { name, logFile: logFile ? path.resolve(dest, logFile) : undefined, endpointUrl: safeReportUrl(endpointUrl), active: enabled };
+    });
+    const consoleUrl = process.env.CONSOLE_TELEMETRY_URL ?? process.env.CONSOLE_URL ?? config.console_telemetry_url ?? config.console_url ?? "";
+    const explicitEndpoint = process.env.CONSOLE_TELEMETRY_ENDPOINT_URL ?? config.console_telemetry_endpoint_url ?? "";
+    const endpointUrl = deriveConsoleEndpoint(consoleUrl, explicitEndpoint);
+    const allowed = endpointAllowed(endpointUrl, allowNetwork);
+    const timeoutMs = Number.parseInt(flagString(args.flags, "timeout-ms", "2000") ?? "2000", 10);
+    const reachability = await checkConsoleReachability(endpointUrl, Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 2000, allowNetwork);
+    const warnings = reportWarnings(configFile, endpointUrl, allowed, allowNetwork);
+    return {
+        ok: enabled && (!endpointUrl || (allowed && reachability.ok !== false)),
+        destination: dest,
+        telemetry: {
+            configFile,
+            configExists: fs.existsSync(configFile),
+            enabled,
+            dataDir,
+            sessionDir,
+            channels: channelReports,
+            activeSinks: activeSinks(enabled, channelReports, endpointUrl, allowed),
+        },
+        console: {
+            sink: endpointUrl ? "console" : "local-only",
+            url: safeReportUrl(consoleUrl),
+            endpointUrl: safeReportUrl(endpointUrl),
+            endpointAllowed: allowed,
+            tokenConfigured: Boolean(process.env.CONSOLE_TELEMETRY_TOKEN ?? process.env.CONSOLE_AUTH_TOKEN ?? config.console_telemetry_token),
+            tenantConfigured: Boolean(process.env.CONSOLE_TENANT_ID ?? config.console_tenant_id),
+            reachability,
+        },
+        warnings,
+    };
+}
+function reportWarnings(configFile, endpointUrl, allowed, allowNetwork) {
+    const warnings = [];
+    if (!fs.existsSync(configFile))
+        warnings.push("telemetry.conf was not found under destination scripts/telemetry");
+    if (endpointUrl && !allowed)
+        warnings.push(allowNetwork ? "Console endpoint is malformed or contains credentials" : "Console endpoint is not allowed without --allow-network; local http(s) endpoints are allowed by default");
+    return warnings;
+}
+function printText(report) {
+    console.log(`Telemetry doctor for ${report.destination}`);
+    console.log(`Config: ${report.telemetry.configFile} (${report.telemetry.configExists ? "found" : "missing"})`);
+    console.log(`Telemetry enabled: ${report.telemetry.enabled}`);
+    console.log(`Local telemetry dir: ${report.telemetry.dataDir}`);
+    console.log(`Active sinks: ${report.telemetry.activeSinks.length ? report.telemetry.activeSinks.join(", ") : "none"}`);
+    console.log(`Console endpoint: ${report.console.endpointUrl || "not configured"}`);
+    console.log(`Console reachability: ${report.console.reachability.checked ? (report.console.reachability.ok ? "ok" : `failed (${report.console.reachability.error ?? report.console.reachability.statusCode ?? "unknown"})`) : "not checked"}`);
+    for (const warning of report.warnings)
+        console.log(`Warning: ${warning}`);
+}
+export async function main(argv = process.argv.slice(2)) {
+    const args = parseArgs(argv);
+    if (flagBool(args.flags, "help") || flagBool(args.flags, "h")) {
+        usage();
+        return 0;
+    }
+    const report = await buildReport(argv);
+    if (flagBool(args.flags, "json"))
+        console.log(JSON.stringify(report, null, 2));
+    else
+        printText(report);
+    return report.ok ? 0 : 1;
+}

package/build/src/cli/usage-feedback.js

@@ -0,0 +1,443 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parseArgs, flagBool, flagList, flagString } from "../lib/args.js";
+const VALID_RESULTS = new Set(["success", "partial", "failure", "not_verified"]);
+function telemetryDir(flags) {
+    return path.resolve(flagString(flags, "telemetry-dir", process.env.TELEMETRY_DATA_DIR ?? ".telemetry") ?? ".telemetry");
+}
+function ensureSafeDir(dir) {
+    let current = path.resolve(dir);
+    const missing = [];
+    while (!fs.existsSync(current)) {
+        missing.push(current);
+        current = path.dirname(current);
+    }
+    if (fs.lstatSync(current).isSymbolicLink())
+        throw new Error(`unsafe telemetry path contains symlink: ${current}`);
+    const rel = path.relative(current, dir).split(path.sep).filter(Boolean);
+    let cursor = current;
+    for (const part of rel) {
+        cursor = path.join(cursor, part);
+        if (fs.existsSync(cursor) && fs.lstatSync(cursor).isSymbolicLink())
+            throw new Error(`unsafe telemetry path contains symlink: ${cursor}`);
+    }
+    for (const item of missing.reverse())
+        fs.mkdirSync(item);
+}
+function appendJsonl(file, record) {
+    try {
+        if (fs.lstatSync(file).isSymbolicLink())
+            throw new Error(`refusing to write symlinked file: ${file}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    fs.appendFileSync(file, `${JSON.stringify(record)}\n`, "utf8");
+}
+function readJsonl(file) {
+    if (!fs.existsSync(file))
+        return [];
+    return fs.readFileSync(file, "utf8").split(/\r?\n/).filter(Boolean).map((line) => JSON.parse(line));
+}
+function writeJsonlUpsert(file, rows, key) {
+    const existing = new Map(readJsonl(file).map((row) => [String(row[key]), row]));
+    for (const row of rows)
+        existing.set(String(row[key]), row);
+    fs.writeFileSync(file, Array.from(existing.values()).map((row) => JSON.stringify(row)).join("\n") + (existing.size ? "\n" : ""), "utf8");
+}
+function recordOutcome(argv) {
+    const { flags } = parseArgs(argv);
+    const sessionId = flagString(flags, "session-id");
+    const result = flagString(flags, "result");
+    if (!sessionId)
+        throw new Error("--session-id is required");
+    if (!result || !VALID_RESULTS.has(result))
+        throw new Error("--result must be success, partial, failure, or not_verified");
+    const dir = telemetryDir(flags);
+    ensureSafeDir(dir);
+    const record = {
+        schema_version: "1",
+        outcome_id: `${sessionId}:${flagString(flags, "task-slug", "outcome")}`,
+        recorded_at: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+        session_id: sessionId,
+        runtime_session_id: flagString(flags, "runtime-session-id"),
+        runtime: flagString(flags, "runtime", "codex"),
+        repo: flagString(flags, "repo"),
+        agent: flagString(flags, "agent"),
+        profile_id: flagString(flags, "profile-id"),
+        prompt_id: flagString(flags, "prompt-id"),
+        prompt_variant: flagString(flags, "prompt-variant"),
+        skill_ids: flagList(flags, "skill-id"),
+        skill_variant: flagString(flags, "skill-variant"),
+        task_type: flagString(flags, "task-type"),
+        task_slug: flagString(flags, "task-slug"),
+        result,
+        quality_score: flagString(flags, "quality-score") ? Number(flagString(flags, "quality-score")) : null,
+        human_minutes_saved: flagString(flags, "human-minutes-saved") ? Number(flagString(flags, "human-minutes-saved")) : null,
+        rework_required: flagBool(flags, "rework-required"),
+        notes: flagString(flags, "notes"),
+        evidence: flagList(flags, "evidence"),
+    };
+    appendJsonl(path.join(dir, "outcomes.jsonl"), record);
+    return 0;
+}
+function normalize(input, runtime, flags, fallbackSource = "flow-agents") {
+    const groups = new Map();
+    for (const event of input)
+        groups.set(String(event.session_id ?? "unknown"), [...(groups.get(String(event.session_id ?? "unknown")) ?? []), event]);
+    return Array.from(groups, ([sessionId, events]) => ({
+        schema_version: "1",
+        session_id: sessionId,
+        source_id: flagString(flags, "source-id") ?? String(events.find((event) => event.repo)?.repo ?? fallbackSource),
+        runtime,
+        repo: flagString(flags, "repo") ?? String(events.find((event) => event.repo)?.repo ?? ""),
+        repo_root: flagString(flags, "repo-root"),
+        agent: flagString(flags, "agent") ?? String(events.find((event) => event.agent)?.agent?.name ?? "dev"),
+        profile_id: flagString(flags, "profile-id") ?? String(events.find((event) => event.profile_id)?.profile_id ?? ""),
+        prompt_id: flagString(flags, "prompt-id") ?? String(events.find((event) => event.prompt_id)?.prompt_id ?? ""),
+        prompt_variant: flagString(flags, "prompt-variant") ?? String(events.find((event) => event.prompt_variant)?.prompt_variant ?? ""),
+        skill_ids: flagList(flags, "skill-id").length ? flagList(flags, "skill-id") : (events.find((event) => Array.isArray(event.skill_ids))?.skill_ids ?? []),
+        skill_variant: flagString(flags, "skill-variant") ?? String(events.find((event) => event.skill_variant)?.skill_variant ?? ""),
+        started_at: events[0]?.timestamp,
+        ended_at: events[events.length - 1]?.timestamp,
+        turns: events.filter((event) => String(event.event_type ?? "").includes("turn.user")).length,
+        tool_invocations: events.filter((event) => String(event.event_type ?? "") === "tool.invoke").length,
+        delegations: events.filter((event) => String(event.event_type ?? "").includes("delegate")).length,
+        permission_requests: events.filter((event) => String(event.event_type ?? "").includes("permission")).length,
+    }));
+}
+function importTelemetry(argv, defaultRuntime) {
+    const { flags } = parseArgs(argv);
+    const runtime = defaultRuntime ?? flagString(flags, "runtime", "codex") ?? "codex";
+    const input = flagString(flags, "input-full-jsonl") ?? path.join(flagString(flags, "input-telemetry-dir") ?? "", "full.jsonl");
+    if (!input || !fs.existsSync(input))
+        throw new Error(`input telemetry file does not exist: ${input}`);
+    const dir = telemetryDir(flags);
+    ensureSafeDir(dir);
+    const inputDir = flagString(flags, "input-telemetry-dir");
+    const fallbackSource = inputDir ? path.basename(path.resolve(inputDir)) : "flow-agents";
+    writeJsonlUpsert(path.join(dir, "normalized-sessions.jsonl"), normalize(readJsonl(input), runtime, flags, fallbackSource), "session_id");
+    return 0;
+}
+function artifactOutcomes(artifactPath, flags) {
+    const files = [];
+    const stat = fs.statSync(artifactPath);
+    if (stat.isDirectory()) {
+        for (const name of fs.readdirSync(artifactPath, { recursive: true }))
+            if (name.endsWith(".md"))
+                files.push(path.join(artifactPath, name));
+    }
+    else
+        files.push(artifactPath);
+    return files.flatMap((file) => {
+        const text = fs.readFileSync(file, "utf8");
+        const status = text.match(/^status:\s*(.+)$/m)?.[1].trim() ?? "";
+        const type = text.match(/^type:\s*(.+)$/m)?.[1].trim() ?? "";
+        const terminal = ["delivered", "accepted", "done"].includes(status);
+        if (!terminal && !flagBool(flags, "include-open"))
+            return [];
+        const title = text.split(/\r?\n/).find((line) => line.startsWith("# "))?.slice(2).trim() ?? path.basename(file, ".md");
+        const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+        return [{ schema_version: "1", outcome_id: `artifact:${file}`, recorded_at: new Date().toISOString(), session_id: slug, runtime: flagString(flags, "runtime", "codex"), repo: flagString(flags, "repo"), profile_id: flagString(flags, "profile-id"), prompt_id: flagString(flags, "prompt-id"), skill_ids: flagList(flags, "skill-id"), task_type: type || "deliver", task_slug: slug, result: terminal ? "success" : status === "failed" ? "failure" : "not_verified", quality_score: null, human_minutes_saved: null, rework_required: false, evidence: [file] }];
+    });
+}
+function syncArtifacts(argv) {
+    const { flags } = parseArgs(argv);
+    const dir = telemetryDir(flags);
+    ensureSafeDir(dir);
+    const artifacts = flagList(flags, "artifact-dir");
+    const records = (artifacts.length ? artifacts : [".flow-agents"]).flatMap((item) => fs.existsSync(item) ? artifactOutcomes(item, flags) : []);
+    writeJsonlUpsert(path.join(dir, "outcomes.jsonl"), records, "outcome_id");
+    if (!flagBool(flags, "quiet"))
+        console.log(`synced ${records.length} artifact outcome(s) to ${path.join(dir, "outcomes.jsonl")}`);
+    return 0;
+}
+function rows(dir) {
+    const full = fs.existsSync(path.join(dir, "full.jsonl")) ? path.join(dir, "full.jsonl") : path.join(dir, "sample-full.jsonl");
+    const outcomes = fs.existsSync(path.join(dir, "outcomes.jsonl")) ? path.join(dir, "outcomes.jsonl") : path.join(dir, "sample-outcomes.jsonl");
+    return {
+        sessions: [
+            ...readJsonl(path.join(dir, "normalized-sessions.jsonl")),
+            ...readJsonl(path.join(dir, "sessions.jsonl")),
+            ...normalize(readJsonl(full), "codex", {}, path.basename(path.resolve(dir))),
+        ],
+        outcomes: readJsonl(outcomes),
+    };
+}
+function reportData(dirs, groupBy) {
+    const sessions = dirs.flatMap((dir) => rows(dir).sessions);
+    const outcomes = dirs.flatMap((dir) => rows(dir).outcomes);
+    const outcomesBySession = new Map();
+    for (const outcome of outcomes) {
+        const key = String(outcome.session_id ?? "unknown");
+        outcomesBySession.set(key, [...(outcomesBySession.get(key) ?? []), outcome]);
+    }
+    const success = outcomes.filter((outcome) => outcome.result === "success").length;
+    const groups = new Map();
+    const groupValue = (session, sessionOutcomes) => {
+        if (!groupBy)
+            return "all";
+        if (groupBy === "source")
+            return String(session.source_id ?? "unknown");
+        if (groupBy === "skill_id")
+            return Array.isArray(session.skill_ids) && session.skill_ids.length ? session.skill_ids.join(",") : "unknown";
+        if (groupBy === "task_type")
+            return String(sessionOutcomes.find((outcome) => outcome.task_type)?.task_type ?? "unknown");
+        return String(session[groupBy] ?? "unknown");
+    };
+    for (const session of sessions) {
+        const sessionOutcomes = outcomesBySession.get(String(session.session_id ?? "unknown")) ?? [];
+        const key = cleanLabel(groupValue(session, sessionOutcomes));
+        const entry = groups.get(key) ?? { sessions: 0, outcomes: 0, success: 0, tools: [], rework: 0 };
+        entry.sessions += 1;
+        entry.outcomes += sessionOutcomes.length;
+        entry.success += sessionOutcomes.filter((outcome) => outcome.result === "success").length;
+        if (session.tool_invocations !== undefined && session.tool_invocations !== null)
+            entry.tools.push(Number(session.tool_invocations));
+        entry.rework += sessionOutcomes.filter((outcome) => outcome.rework_required).length;
+        groups.set(key, entry);
+    }
+    const sessionIdsWithOutcomes = new Set(outcomes.map((outcome) => outcome.session_id));
+    const avgTools = sessions.length ? sessions.reduce((total, session) => total + Number(session.tool_invocations ?? 0), 0) / sessions.length : null;
+    const reworkCount = outcomes.filter((outcome) => outcome.rework_required).length;
+    return {
+        summary: {
+            sessions: sessions.length,
+            sessions_with_outcomes: sessionIdsWithOutcomes.size,
+            outcomes: outcomes.length,
+            success_rate: outcomes.length ? success / outcomes.length : null,
+            avg_tool_invocations: avgTools,
+            rework_rate: outcomes.length ? reworkCount / outcomes.length : null,
+        },
+        sources: Array.from(new Set(sessions.map((session) => String(session.source_id ?? "unknown")))).sort(),
+        groups: Array.from(groups, ([key, entry]) => ({
+            key,
+            group: key,
+            name: key,
+            sessions: entry.sessions,
+            outcomes: entry.outcomes,
+            success_rate: entry.outcomes ? entry.success / entry.outcomes : null,
+            avg_tool_invocations: entry.tools.length ? entry.tools.reduce((a, b) => a + b, 0) / entry.tools.length : null,
+            rework_rate: entry.outcomes ? entry.rework / entry.outcomes : null,
+        })).sort((a, b) => String(a.key).localeCompare(String(b.key))),
+    };
+}
+function reportPath(output, dir, force) {
+    if (!output)
+        return undefined;
+    const reports = path.join(dir, "reports");
+    if (fs.existsSync(reports) && fs.lstatSync(reports).isSymbolicLink())
+        throw new Error("reports directory is symlinked");
+    let relativeOutput = output.replace(new RegExp(`^${path.basename(dir)}/reports/`), "").replace(/^reports\//, "");
+    let target = path.isAbsolute(output) ? output : path.join(reports, relativeOutput);
+    target = path.resolve(target);
+    if (!target.startsWith(path.resolve(reports) + path.sep))
+        throw new Error("report output must be inside telemetry reports directory");
+    try {
+        if (fs.lstatSync(target).isSymbolicLink())
+            throw new Error("report output is symlinked");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (fs.existsSync(target) && !force)
+        throw new Error("report output exists; rerun with --force");
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    return target;
+}
+function html(content) {
+    return `<!doctype html><html><body><h1>Usage Dashboard</h1><h2>What Needs Attention</h2><h2>Measurement state</h2><h2>Data Coverage</h2><h2>Outcome Mix</h2><h2>Missing Label Drilldown</h2><pre>${escapeHtml(content)}</pre></body></html>`;
+}
+function cleanLabel(value) {
+    return String(value ?? "unknown").replace(/[\r\n\t\x00-\x1f]+/g, " ").split(/\s+/).filter(Boolean).join(" ") || "unknown";
+}
+function escapeHtml(value) {
+    return String(value ?? "")
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+function markdownCell(value) {
+    return cleanLabel(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+}
+function fmtRate(value) {
+    return typeof value === "number" ? `${(value * 100).toFixed(1)}%` : "n/a";
+}
+function fmtNum(value) {
+    return typeof value === "number" ? String(Number.isInteger(value) ? value : Number(value.toFixed(2))) : "n/a";
+}
+function markdownReport(data, groupBy) {
+    const summary = data.summary;
+    const groups = data.groups;
+    const lines = [
+        "# Agent Usage Feedback Report",
+        "",
+        "## Summary",
+        "",
+        `- Sessions: ${summary.sessions}`,
+        `- Sessions with outcomes: ${summary.sessions_with_outcomes}`,
+        `- Success rate: ${fmtRate(summary.success_rate)}`,
+        `- Avg tool invocations: ${fmtNum(summary.avg_tool_invocations)}`,
+        `- Rework rate: ${fmtRate(summary.rework_rate)}`,
+    ];
+    if (groupBy) {
+        lines.push("", `## Groups by ${groupBy}`, "", "| Group | Sessions | Outcomes | Success rate | Avg tool invocations | Rework rate |", "| --- | ---: | ---: | ---: | ---: | ---: |");
+        for (const group of groups) {
+            lines.push(`| ${markdownCell(group.key)} | ${group.sessions} | ${group.outcomes} | ${fmtRate(group.success_rate)} | ${fmtNum(group.avg_tool_invocations)} | ${fmtRate(group.rework_rate)} |`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+function report(argv) {
+    const { flags } = parseArgs(argv);
+    const dirs = flagList(flags, "telemetry-dir").map((dir) => path.resolve(dir));
+    dirs.forEach(ensureSafeDir);
+    const data = reportData(dirs, flagString(flags, "group-by"));
+    const format = flagString(flags, "format", "markdown");
+    const out = reportPath(flagString(flags, "output"), dirs[0], flagBool(flags, "force"));
+    let body;
+    if (format === "json")
+        body = JSON.stringify(data, null, 2);
+    else if (format === "html")
+        body = html(JSON.stringify(data));
+    else
+        body = markdownReport(data, flagString(flags, "group-by"));
+    if (out)
+        fs.writeFileSync(out, body, "utf8");
+    else
+        console.log(body);
+    return 0;
+}
+function dashboard(argv) {
+    const { flags } = parseArgs(argv);
+    syncArtifacts(argv);
+    const dir = telemetryDir(flags);
+    const out = reportPath(flagString(flags, "output", "dashboard.html"), dir, flagBool(flags, "force"));
+    const outcomes = readJsonl(path.join(dir, "outcomes.jsonl"));
+    fs.writeFileSync(out, html(outcomes.map((o) => String(o.task_slug)).join("\n")), "utf8");
+    if (!flagBool(flags, "quiet"))
+        console.log(`dashboard written to ${out}`);
+    return 0;
+}
+function registerProject(argv) {
+    const { flags } = parseArgs(argv);
+    const globalDir = path.resolve(flagString(flags, "global-dir", path.join(os.homedir(), ".local", "share", "flow-agents", "usage-feedback")) ?? "");
+    ensureSafeDir(globalDir);
+    const repoRoot = path.resolve(flagString(flags, "repo-root", ".") ?? ".");
+    const name = flagString(flags, "name", path.basename(repoRoot)) ?? path.basename(repoRoot);
+    const record = { name, repo_root: repoRoot, artifact_dir: path.join(repoRoot, ".flow-agents"), input_telemetry_dir: path.join(repoRoot, ".telemetry"), runtime: flagString(flags, "runtime", "codex"), repo: flagString(flags, "repo", name), agent: flagString(flags, "agent"), profile_id: flagString(flags, "profile-id"), prompt_id: flagString(flags, "prompt-id"), prompt_variant: flagString(flags, "prompt-variant"), skill_ids: flagList(flags, "skill-id"), skill_variant: flagString(flags, "skill-variant") };
+    const registryFile = path.join(globalDir, "projects.json");
+    const existing = fs.existsSync(registryFile) ? JSON.parse(fs.readFileSync(registryFile, "utf8")) : { projects: [] };
+    const projects = Array.isArray(existing) ? existing : Array.isArray(existing.projects) ? existing.projects : [];
+    const index = projects.findIndex((project) => project.name === name || project.repo_root === repoRoot);
+    if (index >= 0)
+        projects[index] = { ...projects[index], ...record };
+    else
+        projects.push(record);
+    fs.writeFileSync(registryFile, `${JSON.stringify({ projects }, null, 2)}\n`, "utf8");
+    console.log(`registered ${record.name} in ${path.join(globalDir, "projects.json")}`);
+    return 0;
+}
+function loadProjects(globalDir) {
+    const file = path.join(globalDir, "projects.json");
+    if (!fs.existsSync(file))
+        return [];
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    return Array.isArray(data) ? data : Array.isArray(data.projects) ? data.projects : [];
+}
+function syncProject(project, globalDir) {
+    const name = String(project.name ?? project.repo ?? "project").replace(/[^a-zA-Z0-9_.-]+/g, "-") || "project";
+    const store = path.join(globalDir, "projects", name);
+    ensureSafeDir(store);
+    const artifactDir = String(project.artifact_dir ?? path.join(String(project.repo_root), ".flow-agents"));
+    const flags = {
+        "repo": String(project.repo ?? name),
+        "runtime": String(project.runtime ?? "codex"),
+        "agent": project.agent ? String(project.agent) : "",
+        "profile-id": project.profile_id ? String(project.profile_id) : "",
+        "prompt-id": project.prompt_id ? String(project.prompt_id) : "",
+        "prompt-variant": project.prompt_variant ? String(project.prompt_variant) : "",
+        "skill-id": Array.isArray(project.skill_ids) ? project.skill_ids.map(String) : [],
+        "skill-variant": project.skill_variant ? String(project.skill_variant) : "",
+        "include-open": true,
+    };
+    const outcomes = fs.existsSync(artifactDir) ? artifactOutcomes(artifactDir, flags) : [];
+    writeJsonlUpsert(path.join(store, "outcomes.jsonl"), outcomes, "outcome_id");
+}
+function discoverProjects(root) {
+    if (!fs.existsSync(root))
+        return [];
+    const candidates = [root, ...fs.readdirSync(root).map((name) => path.join(root, name))];
+    return candidates.filter((candidate) => fs.existsSync(path.join(candidate, ".flow-agents"))).map((repoRoot) => {
+        const name = path.basename(repoRoot);
+        return { name, repo: name, repo_root: repoRoot, artifact_dir: path.join(repoRoot, ".flow-agents"), input_telemetry_dir: path.join(repoRoot, ".telemetry"), runtime: "codex", skill_ids: [] };
+    });
+}
+function syncProjects(argv) {
+    const { flags } = parseArgs(argv);
+    const globalDir = path.resolve(flagString(flags, "global-dir", path.join(os.homedir(), ".local", "share", "flow-agents", "usage-feedback")) ?? "");
+    ensureSafeDir(globalDir);
+    if (flagString(flags, "repo-root"))
+        registerProject(argv);
+    for (const project of loadProjects(globalDir))
+        syncProject(project, globalDir);
+    return 0;
+}
+function globalDashboard(argv) {
+    const { flags } = parseArgs(argv);
+    const globalDir = path.resolve(flagString(flags, "global-dir", path.join(os.homedir(), ".local", "share", "flow-agents", "usage-feedback")) ?? "");
+    ensureSafeDir(globalDir);
+    const discovered = flagList(flags, "discover").flatMap(discoverProjects);
+    if (discovered.length) {
+        const existing = loadProjects(globalDir);
+        const merged = [...existing];
+        for (const project of discovered)
+            if (!merged.some((item) => item.name === project.name || item.repo_root === project.repo_root))
+                merged.push(project);
+        fs.writeFileSync(path.join(globalDir, "projects.json"), `${JSON.stringify({ projects: merged }, null, 2)}\n`, "utf8");
+    }
+    for (const project of loadProjects(globalDir))
+        syncProject(project, globalDir);
+    const dirs = fs.existsSync(path.join(globalDir, "projects")) ? fs.readdirSync(path.join(globalDir, "projects")).map((name) => path.join(globalDir, "projects", name)) : [];
+    const data = reportData(dirs, "repo");
+    const out = reportPath(flagString(flags, "output", "global-dashboard.html"), globalDir, flagBool(flags, "force"));
+    const projectNames = loadProjects(globalDir).map((project) => String(project.name ?? project.repo ?? "")).filter(Boolean).join("\n");
+    fs.writeFileSync(out, html(`${markdownReport(data, "repo")}\n${projectNames}`), "utf8");
+    return 0;
+}
+export function main(argv = process.argv.slice(2)) {
+    try {
+        const [command, ...rest] = argv;
+        if (command === "record-outcome")
+            return recordOutcome(rest);
+        if (command === "import-codex")
+            return importTelemetry(rest, "codex");
+        if (command === "import-telemetry")
+            return importTelemetry(rest);
+        if (command === "sync-artifacts")
+            return syncArtifacts(rest);
+        if (command === "report")
+            return report(rest);
+        if (command === "dashboard")
+            return dashboard(rest);
+        if (command === "register-project")
+            return registerProject(rest);
+        if (command === "sync-projects")
+            return syncProjects(rest);
+        if (command === "global-dashboard")
+            return globalDashboard(rest);
+        console.error("usage-feedback command required");
+        return 2;
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    process.exit(main());