iteration-cli 0.4.0

package/README.md

@@ -0,0 +1,21 @@
+# Iteration CLI
+
+Install one CLI for Iteration's supported coding-agent sources:
+
+```sh
+npm install --global iteration-cli
+iteration connect codex
+iteration status codex
+```
+
+The Codex collector currently runs on macOS with Node.js 22 or later. `iteration connect codex --include-history` also imports earlier local sessions after you approve access. Run `iteration help` for the available commands.
+
+If you previously installed the Codex-specific package, remove it with the package manager you used:
+
+```sh
+pnpm remove --global iteration-codex-collector
+# Or, if you installed it with npm:
+npm uninstall --global iteration-codex-collector
+```
+
+Then install `iteration-cli` and run `iteration start codex`. This points the existing background collector at the new CLI. Its local configuration and pending events remain in place.

package/dist/clerk-device-auth.d.ts

@@ -0,0 +1,5 @@
+export declare function authenticateAndEnrollCollector(endpoint: URL, deviceNameValue: string, organizationId: string | null): Promise<Readonly<{
+    token: string;
+    deviceId: string;
+    organizationName: string;
+}>>;

package/dist/clerk-device-auth.js

@@ -0,0 +1,276 @@
+import { execFile } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { promisify } from "node:util";
+import { parseCollectorEnrollmentResponse, } from "iteration-trace-contracts";
+import * as z from "zod";
+const execFileAsync = promisify(execFile);
+const serverAuthConfigSchema = z
+    .object({
+    issuerUrl: z.url(),
+    clientId: z.string().min(1),
+})
+    .strict();
+const oauthMetadataSchema = z.object({
+    device_authorization_endpoint: z.url(),
+    token_endpoint: z.url(),
+    issuer: z.url().optional(),
+});
+const deviceCodeSchema = z.object({
+    device_code: z.string().min(1),
+    user_code: z.string().min(1),
+    verification_uri: z.url(),
+    verification_uri_complete: z.url().optional(),
+    expires_in: z.number().int().min(1).max(86_400),
+    interval: z.number().int().min(1).max(3_600),
+});
+const oauthTokenSchema = z.object({
+    access_token: z.string().min(1),
+});
+const oauthErrorSchema = z.object({
+    error: z.string().min(1),
+    error_description: z.string().optional(),
+});
+function apiRoute(endpoint, relativePath) {
+    return new URL(relativePath, endpoint);
+}
+async function responseJson(response) {
+    try {
+        return await response.json();
+    }
+    catch (error) {
+        throw new Error("The authentication server returned invalid JSON.", {
+            cause: error,
+        });
+    }
+}
+async function loadOAuthConfiguration(endpoint) {
+    const response = await fetch(apiRoute(endpoint, "./collector-auth/config"), {
+        signal: AbortSignal.timeout(10_000),
+    });
+    const body = await responseJson(response);
+    if (!response.ok) {
+        throw new Error(response.status === 503
+            ? "Collector sign-in is not configured on the Iteration server."
+            : "Could not load collector sign-in configuration.");
+    }
+    const parsed = serverAuthConfigSchema.safeParse(body);
+    if (!parsed.success) {
+        throw new Error("Collector sign-in configuration has an invalid shape.");
+    }
+    const issuer = new URL(parsed.data.issuerUrl);
+    if (issuer.protocol !== "https:" ||
+        issuer.username !== "" ||
+        issuer.password !== "" ||
+        issuer.pathname !== "/" ||
+        issuer.search !== "" ||
+        issuer.hash !== "") {
+        throw new Error("The configured Clerk issuer URL is invalid.");
+    }
+    return { issuerUrl: issuer.origin, clientId: parsed.data.clientId };
+}
+async function discoverDeviceEndpoints(issuerUrl) {
+    const issuer = new URL(issuerUrl);
+    const response = await fetch(new URL(".well-known/oauth-authorization-server", issuer), { signal: AbortSignal.timeout(10_000) });
+    if (!response.ok) {
+        throw new Error("Clerk OAuth device authorization is unavailable.");
+    }
+    const parsed = oauthMetadataSchema.safeParse(await responseJson(response));
+    if (!parsed.success) {
+        throw new Error("Clerk OAuth metadata does not advertise device authorization.");
+    }
+    const deviceAuthorizationUrl = new URL(parsed.data.device_authorization_endpoint);
+    const tokenUrl = new URL(parsed.data.token_endpoint);
+    if (deviceAuthorizationUrl.protocol !== "https:" ||
+        tokenUrl.protocol !== "https:" ||
+        deviceAuthorizationUrl.origin !== issuer.origin ||
+        tokenUrl.origin !== issuer.origin) {
+        throw new Error("Clerk OAuth metadata contains an unexpected endpoint.");
+    }
+    return {
+        deviceAuthorizationUrl,
+        tokenUrl,
+    };
+}
+async function openBrowser(url) {
+    try {
+        await execFileAsync("open", [url], { timeout: 5000 });
+    }
+    catch {
+        process.stdout.write("Open the verification link in your browser.\n");
+    }
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function requestDeviceCode(url, clientId) {
+    const body = new URLSearchParams({
+        client_id: clientId,
+        scope: "openid profile email",
+    });
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body,
+        signal: AbortSignal.timeout(10_000),
+    });
+    const payload = await responseJson(response);
+    const parsed = deviceCodeSchema.safeParse(payload);
+    if (!response.ok || !parsed.success) {
+        const providerError = oauthErrorSchema.safeParse(payload);
+        throw new Error(providerError.success
+            ? "Clerk device sign-in could not start: " +
+                (providerError.data.error_description ?? providerError.data.error)
+            : "Clerk returned an invalid device authorization response.");
+    }
+    return parsed.data;
+}
+async function pollForAccessToken(tokenUrl, clientId, deviceCode, expiresIn, initialInterval) {
+    const expiresAt = Date.now() + expiresIn * 1000;
+    let interval = initialInterval;
+    while (Date.now() < expiresAt) {
+        await delay(interval * 1000);
+        if (Date.now() >= expiresAt)
+            break;
+        let response;
+        try {
+            response = await fetch(tokenUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: new URLSearchParams({
+                    client_id: clientId,
+                    grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                    device_code: deviceCode,
+                }),
+                signal: AbortSignal.timeout(10_000),
+            });
+        }
+        catch {
+            continue;
+        }
+        const payload = await responseJson(response);
+        const token = oauthTokenSchema.safeParse(payload);
+        if (response.ok && token.success)
+            return token.data.access_token;
+        const providerError = oauthErrorSchema.safeParse(payload);
+        if (!providerError.success) {
+            throw new Error("Clerk returned an invalid device token response.");
+        }
+        switch (providerError.data.error) {
+            case "authorization_pending":
+                continue;
+            case "slow_down":
+                interval += 5;
+                continue;
+            case "access_denied":
+                throw new Error("You denied Iteration collector access.");
+            case "expired_token":
+                throw new Error("The sign-in code expired. Run init again.");
+            default:
+                throw new Error("Clerk device sign-in failed: " +
+                    (providerError.data.error_description ?? providerError.data.error));
+        }
+    }
+    throw new Error("The sign-in code expired. Run init again.");
+}
+async function clerkDeviceSignIn(configuration) {
+    const endpoints = await discoverDeviceEndpoints(configuration.issuerUrl);
+    const challenge = await requestDeviceCode(endpoints.deviceAuthorizationUrl, configuration.clientId);
+    const verificationUrl = challenge.verification_uri_complete ?? challenge.verification_uri;
+    process.stdout.write("Sign in to Iteration to authorize this collector.\n" +
+        "Code: " +
+        challenge.user_code +
+        "\n" +
+        "Link: " +
+        verificationUrl +
+        "\n");
+    await openBrowser(verificationUrl);
+    return pollForAccessToken(endpoints.tokenUrl, configuration.clientId, challenge.device_code, challenge.expires_in, challenge.interval);
+}
+async function enrollDevice(endpoint, accessToken, deviceName, organizationId) {
+    const body = { deviceName };
+    if (organizationId !== null)
+        body.organizationId = organizationId;
+    const response = await fetch(apiRoute(endpoint, "./collector-auth/enroll"), {
+        method: "POST",
+        headers: {
+            Authorization: "Bearer " + accessToken,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(15_000),
+    });
+    const payload = await responseJson(response);
+    const parsed = parseCollectorEnrollmentResponse(payload);
+    if (response.ok && parsed.success)
+        return parsed.value;
+    const error = z.object({ error: z.string().min(1) }).safeParse(payload);
+    if (error.success) {
+        throw new Error(error.data.error);
+    }
+    throw new Error("The Iteration server returned an invalid enrollment response.");
+}
+async function chooseOrganization(organizations, hasMore) {
+    process.stdout.write("Choose an Iteration workspace for this collector:\n");
+    for (const [index, organization] of organizations.entries()) {
+        process.stdout.write(index + 1 + ". " + organization.name + " (" + organization.id + ")\n");
+    }
+    if (hasMore) {
+        process.stdout.write("More workspaces exist; enter an organization ID to choose one not listed.\n");
+    }
+    if (process.stdin.isTTY !== true) {
+        throw new Error("Run init interactively or pass --organization-id.");
+    }
+    const prompt = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = await prompt.question("Workspace number or organization ID: ");
+        const id = z.uuid().safeParse(answer.trim());
+        if (id.success)
+            return id.data;
+        const selection = z.coerce
+            .number()
+            .int()
+            .min(1)
+            .max(organizations.length)
+            .safeParse(answer.trim());
+        if (!selection.success) {
+            throw new Error("Choose a listed number or enter a valid organization ID.");
+        }
+        const organization = organizations[selection.data - 1];
+        if (organization === undefined) {
+            throw new Error("The selected workspace is not available.");
+        }
+        return organization.id;
+    }
+    finally {
+        prompt.close();
+    }
+}
+export async function authenticateAndEnrollCollector(endpoint, deviceNameValue, organizationId) {
+    const deviceName = z
+        .string()
+        .trim()
+        .min(1)
+        .max(160)
+        .safeParse(deviceNameValue);
+    if (!deviceName.success) {
+        throw new Error("--device-name must contain 1 to 160 characters.");
+    }
+    const configuration = await loadOAuthConfiguration(endpoint);
+    const clerkAccessToken = await clerkDeviceSignIn(configuration);
+    let result = await enrollDevice(endpoint, clerkAccessToken, deviceName.data, organizationId);
+    if (result.status === "choose_organization") {
+        const selectedOrganizationId = await chooseOrganization(result.organizations, result.hasMore);
+        result = await enrollDevice(endpoint, clerkAccessToken, deviceName.data, selectedOrganizationId);
+    }
+    if (result.status !== "enrolled") {
+        throw new Error("The collector could not be assigned to that workspace.");
+    }
+    return {
+        token: result.token,
+        deviceId: result.deviceId,
+        organizationName: result.organizationName,
+    };
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+import os from "node:os";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { parseArgs } from "node:util";
+import * as z from "zod";
+import { authenticateAndEnrollCollector } from "./clerk-device-auth.js";
+import { importCodexHistory } from "./history-import.js";
+import { runCollector } from "./service.js";
+import { installLaunchAgent, launchAgentStatus, uninstallLaunchAgent, } from "./launch-agent.js";
+import { assertFreshCollectorDirectory, collectorPaths, ensureStartableState, loadConfig, outboxSize, pendingEventIds, prepareInitialState, saveConfig, saveState, validateCollectorEndpoint, } from "./storage.js";
+const DEFAULT_INGEST_ENDPOINT = "https://useiteration.com/api/traces/ingest";
+function argumentsForCli() {
+    const parsed = parseArgs({
+        args: process.argv.slice(2),
+        allowPositionals: true,
+        strict: true,
+        options: {
+            help: { type: "boolean" },
+            endpoint: { type: "string" },
+            "device-name": { type: "string" },
+            "organization-id": { type: "string" },
+            "codex-home": { type: "string" },
+            "data-directory": { type: "string" },
+            "include-history": { type: "boolean" },
+            yes: { type: "boolean" },
+        },
+    });
+    if (parsed.positionals.length > 2) {
+        throw new Error("Too many command arguments. Run iteration help for usage.");
+    }
+    return {
+        command: parsed.positionals[0] ?? "help",
+        source: parsed.positionals[1],
+        values: parsed.values,
+    };
+}
+function optionalString(values, name) {
+    const value = values[name];
+    if (value === undefined)
+        return null;
+    const parsed = z.string().min(1).safeParse(value);
+    if (!parsed.success) {
+        throw new Error(`--${name} must be a non-empty string.`);
+    }
+    return parsed.data;
+}
+function usage() {
+    process.stdout.write([
+        "Iteration CLI",
+        "  iteration connect codex [--endpoint URL] [--device-name NAME] [--organization-id UUID] [--include-history] [--codex-home DIR] [--data-directory DIR]",
+        "  iteration status codex [--data-directory DIR]",
+        "  iteration import-history codex [--data-directory DIR] [--yes]",
+        "  iteration start codex [--data-directory DIR]",
+        "  iteration disconnect codex",
+    ].join("\n") + "\n");
+}
+function dataDirectory(values) {
+    return path.resolve(optionalString(values, "data-directory") ??
+        path.join(os.homedir(), ".config", "iteration", "codex-collector"));
+}
+async function initialize(values) {
+    if (process.platform !== "darwin") {
+        throw new Error("Automatic startup is currently supported on macOS only.");
+    }
+    const endpoint = optionalString(values, "endpoint") ?? DEFAULT_INGEST_ENDPOINT;
+    const endpointUrl = validateCollectorEndpoint(endpoint);
+    const deviceName = optionalString(values, "device-name") ?? os.hostname();
+    const organizationId = optionalString(values, "organization-id");
+    const directory = dataDirectory(values);
+    const paths = collectorPaths(directory);
+    const includeHistory = values["include-history"] === true;
+    const codexHome = path.resolve(optionalString(values, "codex-home") ??
+        process.env.CODEX_HOME ??
+        path.join(os.homedir(), ".codex"));
+    await assertFreshCollectorDirectory(paths);
+    const preparedState = await prepareInitialState(codexHome, includeHistory);
+    const enrollment = await authenticateAndEnrollCollector(endpointUrl, deviceName, organizationId);
+    const config = {
+        endpoint: endpointUrl.toString(),
+        token: enrollment.token,
+        codexHome,
+        dataDirectory: directory,
+    };
+    await saveConfig(config, paths);
+    try {
+        await saveState(preparedState, paths);
+    }
+    catch (error) {
+        throw new Error("Collector access was approved, but local setup did not finish. Run iteration start codex to repair it.", { cause: error });
+    }
+    let agentFile;
+    try {
+        agentFile = await installLaunchAgent(directory);
+    }
+    catch (error) {
+        throw new Error("Collector access was approved, but background startup failed. Run iteration start codex to retry it.", { cause: error });
+    }
+    process.stdout.write(`Collector installed for ${enrollment.organizationName} and set to start at login. ${includeHistory ? "Existing sessions will be imported." : "Existing sessions are skipped; new activity will be collected."}\nLaunch agent: ${agentFile}\n`);
+}
+async function importHistory(values) {
+    if (process.platform !== "darwin") {
+        throw new Error("Automatic startup is currently supported on macOS only.");
+    }
+    const directory = dataDirectory(values);
+    const paths = collectorPaths(directory);
+    const config = await loadConfig(paths);
+    const estimate = (await importCodexHistory(config, paths, false)).size;
+    process.stdout.write(`Found ${estimate.files} local Codex session files (${estimate.bytes} bytes). History may include prompts, code, and tool output that workspace members can read.\n`);
+    if (values.yes !== true) {
+        process.stdout.write("No changes made. Run iteration import-history codex --yes to confirm this upload.\n");
+        return;
+    }
+    const result = await importCodexHistory(config, paths, true);
+    process.stdout.write(`History scan scheduled for ${result.size.files} local session files (${result.size.bytes} bytes). Scanning and uploads run in bounded batches and may take time. Older sessions appear under the date Iteration receives them. iteration status codex shows events waiting to upload, not total scan progress.${result.backgroundRunning ? "" : " The collector was not running; run iteration start codex to begin scanning."}\n`);
+}
+async function start(values) {
+    if (process.platform !== "darwin") {
+        throw new Error("Automatic startup is currently supported on macOS only.");
+    }
+    const directory = dataDirectory(values);
+    const paths = collectorPaths(directory);
+    const config = await loadConfig(paths);
+    const repairedState = await ensureStartableState(config, paths);
+    await installLaunchAgent(directory);
+    process.stdout.write(`Collector started. Run iteration status codex to check uploads.${repairedState ? " Incomplete setup was repaired with new activity only; use iteration import-history codex if you want to include earlier local sessions." : ""}\n`);
+}
+async function status(values) {
+    const paths = collectorPaths(dataDirectory(values));
+    try {
+        await fs.access(paths.config);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            process.stdout.write("Installed: false\nRunning: false\nPending events: 0\n");
+            return;
+        }
+        throw new Error(`Could not inspect collector config at ${paths.config}.`, {
+            cause: error,
+        });
+    }
+    await loadConfig(paths);
+    const running = await launchAgentStatus();
+    const [size, ids] = await Promise.all([
+        outboxSize(paths),
+        pendingEventIds(paths),
+    ]);
+    process.stdout.write([
+        "Installed: true",
+        `Running: ${running}`,
+        `Pending events: ${ids.size}`,
+        `Pending bytes: ${size}`,
+    ].join("\n") + "\n");
+}
+async function main() {
+    const { command, source, values } = argumentsForCli();
+    if (values.help === true || command === "help")
+        return usage();
+    if (command === "connect" && source === "codex")
+        return initialize(values);
+    if (command === "run") {
+        if (source !== undefined)
+            throw new Error("The run command takes no source.");
+        return runCollector(optionalString(values, "data-directory") ?? undefined);
+    }
+    if (command === "status" && source === "codex")
+        return status(values);
+    if (command === "import-history" && source === "codex")
+        return importHistory(values);
+    if (command === "start" && source === "codex")
+        return start(values);
+    if (command === "disconnect" && source === "codex") {
+        await uninstallLaunchAgent();
+        process.stdout.write("Collector startup removed. Local pending data was retained.\n");
+        return;
+    }
+    throw new Error(`Unknown Iteration command: ${[command, source].filter(Boolean).join(" ")}. Run iteration help for usage.`);
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : "Unknown collector error."}\n`);
+    process.exitCode = 1;
+});

package/dist/collector.d.ts

@@ -0,0 +1,7 @@
+import { type CollectorConfig, type CollectorPaths } from "./storage.js";
+export declare function scanRolloutsOnce(config: CollectorConfig, paths: CollectorPaths, signal?: AbortSignal): Promise<number>;
+export declare function collectorTick(config: CollectorConfig, paths: CollectorPaths, fetcher?: typeof fetch, signal?: AbortSignal): Promise<Readonly<{
+    discovered: number;
+    uploaded: number;
+    outboxBytes: number;
+}>>;

package/dist/collector.js

@@ -0,0 +1,173 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { parseTraceEventAcknowledgement, } from "iteration-trace-contracts";
+import { parseRolloutLine } from "./rollout.js";
+import { acknowledgeEvents, appendEvents, loadState, nextBatch, outboxSize, pendingEventIds, rolloutFiles, saveState, } from "./storage.js";
+const MAX_SCAN_BYTES_PER_FILE = 16 * 1024 * 1024;
+const MAX_SCAN_BYTES_PER_TICK = 16 * 1024 * 1024;
+const MAX_RECORD_BYTES = 3 * 1024 * 1024;
+const MAX_UPLOAD_BYTES = 3 * 1024 * 1024;
+const MAX_EVENT_BYTES = MAX_UPLOAD_BYTES - 1024;
+const MAX_UPLOADS_PER_TICK = 5;
+const MAX_REQUEST_BYTES = 4 * 1024 * 1024;
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+function logGap(filename, offset, reason) {
+    console.error(JSON.stringify({
+        level: "capture_gap",
+        filename,
+        offset,
+        reason,
+    }));
+}
+export async function scanRolloutsOnce(config, paths, signal) {
+    signal?.throwIfAborted();
+    const state = await loadState(paths);
+    if (!state.initialized ||
+        state.sourceDirectory !== path.resolve(config.codexHome)) {
+        throw new Error("Collector state does not match CODEX_HOME; run iteration connect codex again.");
+    }
+    const cursors = { ...state.cursors };
+    const skipping = new Set(state.skipping);
+    const files = await rolloutFiles(path.join(config.codexHome, "sessions"));
+    const queuedIds = await pendingEventIds(paths);
+    const events = [];
+    let remainingBudget = MAX_SCAN_BYTES_PER_TICK;
+    for (const filename of files) {
+        signal?.throwIfAborted();
+        if (remainingBudget === 0)
+            break;
+        const stats = await fs.stat(filename);
+        let offset = cursors[filename] ?? 0;
+        if (offset > stats.size) {
+            logGap(filename, offset, "rollout_file_shrank_resetting_cursor");
+            offset = 0;
+            skipping.delete(filename);
+        }
+        const bytesToRead = Math.min(stats.size - offset, MAX_SCAN_BYTES_PER_FILE, remainingBudget);
+        if (bytesToRead === 0) {
+            cursors[filename] = offset;
+            continue;
+        }
+        const handle = await fs.open(filename, "r");
+        let buffer;
+        try {
+            buffer = Buffer.alloc(bytesToRead);
+            const result = await handle.read(buffer, 0, bytesToRead, offset);
+            buffer = buffer.subarray(0, result.bytesRead);
+            remainingBudget -= result.bytesRead;
+        }
+        finally {
+            await handle.close();
+        }
+        if (skipping.has(filename)) {
+            const newline = buffer.indexOf(10);
+            if (newline < 0) {
+                cursors[filename] = offset + buffer.length;
+                continue;
+            }
+            offset += newline + 1;
+            buffer = buffer.subarray(newline + 1);
+            skipping.delete(filename);
+        }
+        let lineStart = 0;
+        for (let index = 0; index < buffer.length; index += 1) {
+            if (buffer[index] !== 10)
+                continue;
+            let lineBytes = buffer.subarray(lineStart, index);
+            if (lineBytes.at(-1) === 13)
+                lineBytes = lineBytes.subarray(0, -1);
+            const byteOffset = offset + lineStart;
+            if (lineBytes.length > MAX_RECORD_BYTES) {
+                logGap(filename, byteOffset, "rollout_record_exceeds_scan_limit");
+                lineStart = index + 1;
+                continue;
+            }
+            let line;
+            try {
+                line = UTF8_DECODER.decode(lineBytes);
+            }
+            catch {
+                logGap(filename, byteOffset, "rollout_record_is_not_utf8");
+                lineStart = index + 1;
+                continue;
+            }
+            const parsed = parseRolloutLine(line, filename, byteOffset);
+            if (parsed.kind === "gap")
+                logGap(filename, byteOffset, parsed.reason);
+            if (parsed.kind === "event" && !queuedIds.has(parsed.event.eventId)) {
+                const eventBytes = Buffer.byteLength(JSON.stringify(parsed.event), "utf8");
+                if (eventBytes > MAX_EVENT_BYTES) {
+                    logGap(filename, byteOffset, "normalized_event_exceeds_upload_limit");
+                }
+                else {
+                    events.push(parsed.event);
+                    queuedIds.add(parsed.event.eventId);
+                }
+            }
+            lineStart = index + 1;
+        }
+        if (buffer.length - lineStart > MAX_RECORD_BYTES) {
+            logGap(filename, offset + lineStart, "incomplete_rollout_record_exceeds_scan_limit");
+            skipping.add(filename);
+            lineStart = buffer.length;
+        }
+        cursors[filename] = offset + lineStart;
+    }
+    await appendEvents(events, paths);
+    await saveState({
+        cursors,
+        skipping: [...skipping],
+        sourceDirectory: state.sourceDirectory,
+        initialized: true,
+    }, paths);
+    return events.length;
+}
+async function uploadPendingOnce(config, paths, fetcher = fetch, signal) {
+    let uploaded = 0;
+    for (let attempt = 0; attempt < MAX_UPLOADS_PER_TICK; attempt += 1) {
+        signal?.throwIfAborted();
+        const batch = await nextBatch(paths, MAX_UPLOAD_BYTES);
+        if (batch.length === 0)
+            return uploaded;
+        const body = JSON.stringify({ events: batch });
+        if (Buffer.byteLength(body, "utf8") > MAX_REQUEST_BYTES) {
+            throw new Error("Queued trace batch exceeds the upload request limit.");
+        }
+        const response = await fetcher(config.endpoint, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${config.token}`,
+                "content-type": "application/json",
+            },
+            body,
+            signal: signal
+                ? AbortSignal.any([signal, AbortSignal.timeout(15_000)])
+                : AbortSignal.timeout(15_000),
+        });
+        if (response.status !== 202) {
+            throw new Error(`Trace upload failed with HTTP ${response.status}.`);
+        }
+        let acknowledgement;
+        try {
+            acknowledgement = await response.json();
+        }
+        catch (error) {
+            throw new Error("Trace upload returned an unreadable acknowledgement.", {
+                cause: error,
+            });
+        }
+        const expectedIds = batch.map((event) => event.eventId);
+        const parsed = parseTraceEventAcknowledgement(acknowledgement, expectedIds);
+        if (!parsed.success)
+            throw new Error(parsed.error);
+        await acknowledgeEvents(new Set(parsed.value.acceptedEventIds), paths);
+        uploaded += batch.length;
+    }
+    return uploaded;
+}
+export async function collectorTick(config, paths, fetcher = fetch, signal) {
+    let uploaded = await uploadPendingOnce(config, paths, fetcher, signal);
+    const discovered = await scanRolloutsOnce(config, paths, signal);
+    uploaded += await uploadPendingOnce(config, paths, fetcher, signal);
+    return { discovered, uploaded, outboxBytes: await outboxSize(paths) };
+}