@codetelemetry/connect 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elliot Gardiner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @codetelemetry/connect
+
+The public-safe CodeTelemetry onboarding CLI for Claude Code and Codex. This
+package contains only local client configuration, device authentication, a test
+event, and connectivity verification. CodeTelemetry application, storage,
+planning, host-capacity, dispatch, and infrastructure code are not included.
+
+```bash
+npx -y @codetelemetry/connect login
+npx -y @codetelemetry/connect login --codex
+npx -y @codetelemetry/connect doctor
+npx -y @codetelemetry/connect print-config
+npx -y @codetelemetry/connect --key-env CODETELEMETRY_INGEST_KEY
+```
+
+If you already have an ingest key, `npx -y @codetelemetry/connect <cot_key>` is
+supported for compatibility, but command-line arguments can be visible to other
+local processes. Device login or `--key-env` is preferred. The key is never echoed and tool
+results contain only a masked preview and hash.
+
+Content telemetry (`--enrich`) and repository-path observation
+(`--repository-observation`) are independent explicit opt-ins. The CLI uses only
+CodeTelemetry production endpoints and recognized Claude Code/Codex config paths;
+arbitrary endpoint and filesystem overrides are not part of its public CLI.
+
+Requires Node.js 22.6 or newer.

package/dist/bin/connect.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/connect.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.js";
+run(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/src/cli.d.ts

@@ -0,0 +1,10 @@
+import { type Endpoints } from "./config.ts";
+import { type FetchLike } from "./otlp.ts";
+type RunDeps = {
+    endpointsOverride?: Partial<Endpoints>;
+    fetchImpl?: FetchLike;
+    openBrowser?: (url: string) => boolean;
+    env?: NodeJS.ProcessEnv;
+};
+export declare function run(argv: string[], deps?: RunDeps): Promise<number>;
+export {};

package/dist/src/cli.js

@@ -0,0 +1,172 @@
+import fs from "node:fs";
+import { spawn } from "node:child_process";
+import { onboard } from "./onboard.js";
+import { resolveEndpoints, resolveSettingsPath } from "./config.js";
+import { buildEnvBlock } from "./settings.js";
+import { buildOtelSection, readCodexKey, resolveCodexConfigPath } from "./codexConfig.js";
+import { looksLikeKey, mask } from "./keys.js";
+import { requestDeviceCode, pollForKey } from "./deviceClient.js";
+import { sendTestEvent } from "./otlp.js";
+import { confirmLanded } from "./connectivity.js";
+const VALUE_FLAGS = new Set(["scope", "key-env"]);
+const BOOL_FLAGS = new Set(["codex", "enrich", "repository-observation", "open", "test", "verify", "json", "help", "h"]);
+function parse(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith("--") && arg !== "-h") {
+            positionals.push(arg);
+            continue;
+        }
+        const body = arg === "-h" ? "h" : arg.slice(2);
+        const negative = body.startsWith("no-");
+        const name = negative ? body.slice(3) : body.split("=", 1)[0];
+        if (!BOOL_FLAGS.has(name) && !VALUE_FLAGS.has(name))
+            return `Unknown option --${name}.`;
+        if (VALUE_FLAGS.has(name)) {
+            if (negative)
+                return `--no-${name} is not valid.`;
+            const value = body.includes("=") ? body.slice(body.indexOf("=") + 1) : argv[++i];
+            if (!value || value.startsWith("--"))
+                return `--${name} needs a value.`;
+            flags[name] = value;
+        }
+        else {
+            if (body.includes("="))
+                return `--${name} takes no value.`;
+            flags[name] = !negative;
+        }
+    }
+    return { positionals, flags };
+}
+const HELP = `codetelemetry-connect — connect Claude Code or Codex to CodeTelemetry
+
+Usage:
+  codetelemetry-connect login [options]
+  codetelemetry-connect <cot_key> [options]
+  codetelemetry-connect doctor [options]
+  codetelemetry-connect print-config [options]
+  codetelemetry-connect --key-env <NAME> [options]
+
+Options:
+  --codex                  Configure Codex instead of Claude Code
+  --scope user|project     Claude Code config scope (default: user)
+  --enrich                 Opt in to prompt/body/tool-content telemetry
+  --repository-observation Opt in to repository-path observation hooks
+  --key-env <NAME>          Read an ingest key from an environment variable
+  --no-open                Do not open the device-approval page
+  --no-test                Do not send a test event
+  --no-verify              Do not wait for the test event to land
+  --json                   Print a machine-readable result
+  -h, --help               Show this help`;
+const out = (line) => process.stdout.write(`${line}\n`);
+function defaultOpenBrowser(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(command, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readClaudeKey(settingsPath) {
+    if (!fs.existsSync(settingsPath))
+        return null;
+    try {
+        const value = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+        const headers = value?.env?.OTEL_EXPORTER_OTLP_HEADERS;
+        return typeof headers === "string" ? headers.match(/Bearer\s+(cot_[A-Za-z0-9_-]+)/)?.[1] ?? null : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function run(argv, deps = {}) {
+    const parsed = parse(argv);
+    if (typeof parsed === "string") {
+        out(parsed);
+        return 1;
+    }
+    const { positionals, flags } = parsed;
+    const command = positionals[0];
+    if (positionals.length > 1) {
+        out(`Unexpected argument: ${positionals[1]}`);
+        return 1;
+    }
+    if (flags.help || flags.h || command === "help") {
+        out(HELP);
+        return 0;
+    }
+    if (!command && !flags["key-env"]) {
+        out(HELP);
+        return 1;
+    }
+    const scope = flags.scope ?? "user";
+    if (scope !== "user" && scope !== "project") {
+        out("--scope must be user or project.");
+        return 1;
+    }
+    const client = flags.codex ? "codex" : "claude";
+    const endpoints = resolveEndpoints(deps.endpointsOverride);
+    const configPath = client === "codex" ? resolveCodexConfigPath() : resolveSettingsPath({ scope: scope });
+    const common = {
+        client,
+        endpoints,
+        settings: { scope: scope, enrich: flags.enrich === true, repositoryObservation: flags["repository-observation"] === true },
+        sendTest: flags.test !== false,
+        verify: flags.verify !== false,
+        fetchImpl: deps.fetchImpl,
+        logger: flags.json ? undefined : out,
+    };
+    if (command === "print-config") {
+        out(client === "codex"
+            ? buildOtelSection("cot_<YOUR_INGEST_KEY>", endpoints.ingestEndpoint, flags.enrich === true)
+            : JSON.stringify({ env: buildEnvBlock("<YOUR_INGEST_KEY>", endpoints.ingestEndpoint, flags.enrich === true) }, null, 2));
+        return 0;
+    }
+    if (command === "doctor") {
+        const key = client === "codex" ? readCodexKey(configPath) : readClaudeKey(configPath);
+        if (!key) {
+            out(`No active CodeTelemetry key found in ${configPath}.`);
+            return 1;
+        }
+        if (!flags.json)
+            out(`Re-testing ${mask(key)} → ${endpoints.ingestEndpoint}`);
+        const test = await sendTestEvent({ key, ingestEndpoint: endpoints.ingestEndpoint, fetchImpl: deps.fetchImpl });
+        if (!test.ok)
+            return 1;
+        const verified = await confirmLanded({ key, connectivityUrl: endpoints.connectivityUrl, probeId: test.probeId, fetchImpl: deps.fetchImpl });
+        if (flags.json)
+            out(JSON.stringify({ ok: verified.landed, probeId: test.probeId, elapsedMs: verified.elapsedMs }));
+        else
+            out(verified.landed ? `✓ Telemetry landed in ${verified.elapsedMs}ms` : "Probe not confirmed within timeout.");
+        return verified.landed ? 0 : 1;
+    }
+    if (command === "login") {
+        const code = await requestDeviceCode(endpoints, deps.fetchImpl);
+        const url = `${code.verificationUri}?code=${encodeURIComponent(code.userCode)}`;
+        out(`Approve CodeTelemetry access: ${url}`);
+        out(`Code: ${code.userCode}`);
+        if (flags.open !== false && !flags.json)
+            (deps.openBrowser ?? defaultOpenBrowser)(url);
+        const result = await onboard({ ...common, getKey: () => pollForKey(endpoints, code.deviceCode, { intervalMs: code.interval * 1000, timeoutMs: code.expiresIn * 1000, fetchImpl: deps.fetchImpl }) });
+        if (flags.json)
+            out(JSON.stringify(result, null, 2));
+        return result.ok ? 0 : 1;
+    }
+    const fromEnv = typeof flags["key-env"] === "string" ? (deps.env ?? process.env)[flags["key-env"]]?.trim() : undefined;
+    const key = fromEnv ?? command;
+    if (!looksLikeKey(key)) {
+        out(fromEnv === undefined && flags["key-env"] ? `No valid CodeTelemetry key found in $${String(flags["key-env"])}.` : HELP);
+        return 1;
+    }
+    const result = await onboard({ ...common, key });
+    if (flags.json)
+        out(JSON.stringify(result, null, 2));
+    return result.ok ? 0 : 1;
+}

package/dist/src/codexConfig.d.ts

@@ -0,0 +1,23 @@
+import type { WriteResult } from "./settings.ts";
+export declare function resolveCodexConfigPath(opts?: {
+    path?: string;
+    home?: string;
+    codexHome?: string;
+}): string;
+export declare function buildOtelSection(key: string, ingestEndpoint: string, enrich: boolean): string;
+export declare function mergeOtelBody(body: string[], key: string, ingestEndpoint: string, enrich: boolean): string[];
+export type CodexWriteOptions = {
+    key: string;
+    ingestEndpoint: string;
+    configPath: string;
+    enrich?: boolean;
+    repositoryObservation?: boolean;
+    backup?: boolean;
+};
+export declare function writeCodexConfig(opts: CodexWriteOptions): WriteResult;
+export declare function readCodexKey(configPath: string): string | null;
+export declare function readCodexSummary(configPath: string): {
+    exists: boolean;
+    otelKeys: string[];
+    hasKey: boolean;
+};

package/dist/src/codexConfig.js

@@ -0,0 +1,265 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { assertKey } from "./keys.js";
+import { installCodexRepositoryObservationHook, removeCodexRepositoryObservationHook, validateCodexRepositoryObservationHook, } from "./repositoryHook.js";
+export function resolveCodexConfigPath(opts = {}) {
+    if (opts.path)
+        return path.resolve(opts.path);
+    const codexHome = opts.codexHome ?? process.env.CODEX_HOME;
+    if (codexHome)
+        return path.resolve(codexHome, "config.toml");
+    return path.join(opts.home ?? os.homedir(), ".codex", "config.toml");
+}
+function exporterLine(kind, signal, key, ingestEndpoint) {
+    return `${kind} = { otlp-http = { endpoint = "${ingestEndpoint}/v1/${signal}", protocol = "binary", headers = { authorization = "Bearer ${key}" } } }`;
+}
+const OWNED_KEYS = ["exporter", "trace_exporter", "metrics_exporter"];
+const COMMENT_RE = /^\s*#/;
+function keyOf(line) {
+    if (COMMENT_RE.test(line))
+        return null;
+    const eq = line.indexOf("=");
+    if (eq === -1)
+        return null;
+    const key = line.slice(0, eq).trim().replace(/\s*\.\s*/g, ".");
+    return key && /^[A-Za-z0-9_.\-"']+$/.test(key) ? key : null;
+}
+function rootKey(key) {
+    const q = key[0];
+    if (q === '"' || q === "'") {
+        const end = key.indexOf(q, 1);
+        if (end !== -1)
+            return key.slice(1, end);
+    }
+    return key.split(".")[0];
+}
+function ownedLines(key, ingestEndpoint, enrich) {
+    const lines = [];
+    if (enrich)
+        lines.push("log_user_prompt = true");
+    lines.push(exporterLine("exporter", "logs", key, ingestEndpoint), exporterLine("trace_exporter", "traces", key, ingestEndpoint), exporterLine("metrics_exporter", "metrics", key, ingestEndpoint));
+    return lines;
+}
+export function buildOtelSection(key, ingestEndpoint, enrich) {
+    return ["[otel]", ...ownedLines(key, ingestEndpoint, enrich)].join("\n");
+}
+export function mergeOtelBody(body, key, ingestEndpoint, enrich) {
+    const replaced = new Set(OWNED_KEYS);
+    if (enrich)
+        replaced.add("log_user_prompt");
+    const kept = body.filter((l) => {
+        const k = keyOf(l);
+        return k === null || !replaced.has(rootKey(k));
+    });
+    while (kept.length && kept[kept.length - 1].trim() === "")
+        kept.pop();
+    return [...kept, ...ownedLines(key, ingestEndpoint, enrich)];
+}
+function sectionKeys(enrich) {
+    return enrich ? ["log_user_prompt", ...OWNED_KEYS] : [...OWNED_KEYS];
+}
+function headerName(line) {
+    const text = stripComment(line).trim();
+    if (!text.startsWith("["))
+        return null;
+    const arrayTable = text.startsWith("[[");
+    const closer = arrayTable ? "]]" : "]";
+    if (!text.endsWith(closer) || text.length <= (arrayTable ? 4 : 2))
+        return null;
+    const inner = text.slice(arrayTable ? 2 : 1, text.length - closer.length);
+    const segments = [];
+    let current = "";
+    let quote = null;
+    for (let i = 0; i < inner.length; i++) {
+        const ch = inner[i];
+        if (quote) {
+            if (ch === "\\" && quote === '"')
+                current += inner[++i] ?? "";
+            else if (ch === quote)
+                quote = null;
+            else
+                current += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'")
+            quote = ch;
+        else if (ch === ".") {
+            segments.push(current.trim());
+            current = "";
+        }
+        else if (ch === "[" || ch === "]" || ch === ",")
+            return null;
+        else
+            current += ch;
+    }
+    if (quote)
+        return null;
+    segments.push(current.trim());
+    return segments.some((s) => s === "") ? null : segments.join(".");
+}
+const isHeader = (line) => headerName(line) !== null;
+const isOtelHeader = (line) => headerName(line) === "otel";
+const isOtelSubtable = (line) => (headerName(line) ?? "").startsWith("otel.");
+const MULTILINE_STRING_RE = /"""|'''/;
+function structuralOnly(line) {
+    let out = "";
+    let quote = null;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (quote) {
+            if (ch === "\\" && quote === '"')
+                i++;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'")
+            quote = ch;
+        else if (ch === "#")
+            break;
+        else
+            out += ch;
+    }
+    return out;
+}
+function depthDelta(line) {
+    let d = 0;
+    for (const ch of structuralOnly(line)) {
+        if (ch === "[" || ch === "{")
+            d++;
+        else if (ch === "]" || ch === "}")
+            d--;
+    }
+    return d;
+}
+function findOtelSection(lines) {
+    let depth = 0;
+    let start = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (depth === 0) {
+            if (start === -1) {
+                if (isOtelHeader(lines[i]))
+                    start = i;
+            }
+            else if (i > start && isHeader(lines[i])) {
+                return { start, end: i };
+            }
+        }
+        depth = Math.max(0, depth + depthDelta(lines[i]));
+    }
+    return start === -1 ? null : { start, end: lines.length };
+}
+function hasOtelSubtable(lines) {
+    let depth = 0;
+    for (const line of lines) {
+        if (depth === 0 && isOtelSubtable(line))
+            return true;
+        depth = Math.max(0, depth + depthDelta(line));
+    }
+    return false;
+}
+function splitLines(raw) {
+    const crlf = (raw.match(/\r\n/g) ?? []).length;
+    const lf = (raw.match(/\n/g) ?? []).length - crlf;
+    return { lines: raw.split(/\r?\n/), eol: crlf > lf ? "\r\n" : "\n" };
+}
+export function writeCodexConfig(opts) {
+    const key = assertKey(opts.key);
+    const filePath = path.resolve(opts.configPath);
+    const existed = fs.existsSync(filePath);
+    const raw = existed ? fs.readFileSync(filePath, "utf8") : "";
+    const { lines, eol } = splitLines(raw);
+    if (lines.some((l) => MULTILINE_STRING_RE.test(l))) {
+        throw new Error(`refusing to edit ${filePath}: it uses a multi-line TOML string (""" or '''), whose contents ` +
+            `this writer can't tell apart from real section headers. Configure the [otel] section by hand ` +
+            `(https://codetelemetry.com/docs/data-sources/openai-codex), or remove the multi-line string and retry.`);
+    }
+    if (hasOtelSubtable(lines)) {
+        throw new Error(`refusing to edit ${filePath}: it defines [otel.*] sub-tables this writer can't safely merge. ` +
+            `Remove or inline them, then retry.`);
+    }
+    if (opts.repositoryObservation)
+        validateCodexRepositoryObservationHook(filePath);
+    else
+        removeCodexRepositoryObservationHook(filePath);
+    const section = findOtelSection(lines);
+    let out;
+    if (section === null) {
+        const fresh = buildOtelSection(key, opts.ingestEndpoint, !!opts.enrich).split("\n");
+        const body = lines.length && lines[lines.length - 1] === "" ? lines.slice(0, -1) : lines;
+        out = body.length ? [...body, "", ...fresh] : [...fresh];
+    }
+    else {
+        const { start, end } = section;
+        const merged = mergeOtelBody(lines.slice(start + 1, end), key, opts.ingestEndpoint, !!opts.enrich);
+        out = [...lines.slice(0, start), lines[start], ...merged, ...lines.slice(end)];
+    }
+    const next = out.join(eol).replace(/(\r?\n)+$/, "") + eol;
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    let backupPath = null;
+    if (existed && opts.backup !== false) {
+        backupPath = `${filePath}.bak`;
+        fs.copyFileSync(filePath, backupPath);
+    }
+    fs.writeFileSync(filePath, next, { mode: 0o600 });
+    try {
+        fs.chmodSync(filePath, 0o600);
+    }
+    catch {
+    }
+    if (opts.repositoryObservation)
+        installCodexRepositoryObservationHook(filePath);
+    return { path: filePath, wrote: sectionKeys(!!opts.enrich), backupPath, created: !existed };
+}
+function otelSectionLines(raw) {
+    const { lines } = splitLines(raw);
+    if (lines.some((l) => MULTILINE_STRING_RE.test(l)))
+        return [];
+    const section = findOtelSection(lines);
+    return section === null ? [] : lines.slice(section.start + 1, section.end);
+}
+function activeOtelLines(raw) {
+    return otelSectionLines(raw).filter((l) => keyOf(l) !== null);
+}
+function stripComment(line) {
+    let quote = null;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (quote) {
+            if (ch === "\\" && quote === '"')
+                i++;
+            else if (ch === quote)
+                quote = null;
+        }
+        else if (ch === '"' || ch === "'")
+            quote = ch;
+        else if (ch === "#")
+            return line.slice(0, i);
+    }
+    return line;
+}
+function exporterKeyText(raw) {
+    return activeOtelLines(raw)
+        .filter((l) => {
+        const k = keyOf(l);
+        return k !== null && OWNED_KEYS.includes(rootKey(k));
+    })
+        .map(stripComment)
+        .join("\n");
+}
+export function readCodexKey(configPath) {
+    if (!fs.existsSync(configPath))
+        return null;
+    const m = exporterKeyText(fs.readFileSync(configPath, "utf8")).match(/Bearer\s+(cot_[A-Za-z0-9_-]+)/);
+    return m ? m[1] : null;
+}
+export function readCodexSummary(configPath) {
+    if (!fs.existsSync(configPath))
+        return { exists: false, otelKeys: [], hasKey: false };
+    const raw = fs.readFileSync(configPath, "utf8");
+    const otelKeys = activeOtelLines(raw)
+        .map((l) => keyOf(l))
+        .filter((k) => k !== null);
+    return { exists: true, otelKeys, hasKey: /Bearer\s+cot_/.test(exporterKeyText(raw)) };
+}

package/dist/src/config.d.ts

@@ -0,0 +1,26 @@
+export type Endpoints = {
+    apiBase: string;
+    ingestEndpoint: string;
+    deviceCodeUrl: string;
+    deviceApproveUrl: string;
+    deviceTokenUrl: string;
+    connectivityUrl: string;
+    verificationUri: string;
+    agentCostUrl: string;
+    agentSessionPerformanceUrl: string;
+    agentSimilarErrorsUrl: string;
+    agentSessionSearchUrl: string;
+    agentTaskSizeUrl: string;
+    agentLinearIssueSizeUrl: string;
+};
+export declare function resolveEndpoints(overrides?: Partial<{
+    apiBase: string;
+    ingestEndpoint: string;
+}>): Endpoints;
+export type SettingsScope = "user" | "project";
+export declare function resolveSettingsPath(opts?: {
+    scope?: SettingsScope;
+    path?: string;
+    cwd?: string;
+    home?: string;
+}): string;

package/dist/src/config.js

@@ -0,0 +1,32 @@
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_API_BASE = "https://codetelemetry.com";
+const DEFAULT_INGEST = "https://ingest.codetelemetry.com";
+export function resolveEndpoints(overrides = {}) {
+    const apiBase = (overrides.apiBase || process.env.CODETELEMETRY_API_BASE || DEFAULT_API_BASE).replace(/\/$/, "");
+    const ingestEndpoint = (overrides.ingestEndpoint || process.env.CODETELEMETRY_INGEST_ENDPOINT || DEFAULT_INGEST).replace(/\/$/, "");
+    return {
+        apiBase,
+        ingestEndpoint,
+        deviceCodeUrl: `${apiBase}/api/device/code`,
+        deviceApproveUrl: `${apiBase}/api/device/approve`,
+        deviceTokenUrl: `${apiBase}/api/device/token`,
+        connectivityUrl: `${apiBase}/api/connectivity/check`,
+        verificationUri: `${apiBase}/activate`,
+        agentCostUrl: `${apiBase}/api/agent/cost`,
+        agentSessionPerformanceUrl: `${apiBase}/api/agent/session-performance`,
+        agentSimilarErrorsUrl: `${apiBase}/api/agent/similar-errors`,
+        agentSessionSearchUrl: `${apiBase}/api/agent/session-search`,
+        agentTaskSizeUrl: `${apiBase}/api/agent/task-size`,
+        agentLinearIssueSizeUrl: `${apiBase}/api/agent/linear-issue-size`,
+    };
+}
+export function resolveSettingsPath(opts = {}) {
+    if (opts.path)
+        return path.resolve(opts.path);
+    const scope = opts.scope ?? "user";
+    if (scope === "project") {
+        return path.join(opts.cwd ?? process.cwd(), ".claude", "settings.json");
+    }
+    return path.join(opts.home ?? os.homedir(), ".claude", "settings.json");
+}

package/dist/src/connectivity.d.ts

@@ -0,0 +1,27 @@
+import type { FetchLike } from "./otlp.ts";
+export type CheckResult = {
+    seen: boolean;
+    httpStatus: number;
+};
+export declare function checkOnce(opts: {
+    key: string;
+    connectivityUrl: string;
+    probeId: string;
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+}): Promise<CheckResult>;
+export type ConfirmResult = {
+    landed: boolean;
+    elapsedMs: number;
+    polls: number;
+};
+export declare function confirmLanded(opts: {
+    key: string;
+    connectivityUrl: string;
+    probeId: string;
+    fetchImpl?: FetchLike;
+    intervalMs?: number;
+    timeoutMs?: number;
+    onTick?: (poll: number) => void;
+    now?: () => number;
+}): Promise<ConfirmResult>;

package/dist/src/connectivity.js

@@ -0,0 +1,54 @@
+import { assertKey } from "./keys.js";
+export async function checkOnce(opts) {
+    const key = assertKey(opts.key);
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), opts.timeoutMs ?? 8_000);
+    try {
+        const res = await fetchImpl(opts.connectivityUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${key}` },
+            body: JSON.stringify({ probeId: opts.probeId }),
+            signal: ac.signal,
+        });
+        let seen = false;
+        try {
+            const json = (await res.json());
+            seen = !!json?.seen;
+        }
+        catch {
+        }
+        return { seen, httpStatus: res.status };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function confirmLanded(opts) {
+    const interval = opts.intervalMs ?? 2_000;
+    const timeout = opts.timeoutMs ?? 30_000;
+    const now = opts.now ?? (() => Date.now());
+    const start = now();
+    let polls = 0;
+    while (true) {
+        const remaining = timeout - (now() - start);
+        if (remaining <= 0)
+            return { landed: false, elapsedMs: now() - start, polls };
+        polls += 1;
+        opts.onTick?.(polls);
+        const { seen } = await checkOnce({
+            key: opts.key,
+            connectivityUrl: opts.connectivityUrl,
+            probeId: opts.probeId,
+            fetchImpl: opts.fetchImpl,
+            timeoutMs: Math.min(8_000, remaining),
+        });
+        const elapsedMs = now() - start;
+        if (seen)
+            return { landed: true, elapsedMs, polls };
+        if (elapsedMs + interval >= timeout)
+            return { landed: false, elapsedMs, polls };
+        await sleep(interval);
+    }
+}