@pdpp/local-collector 0.1.0-beta.6 → 0.1.0-beta.8

package/dist/polyfill-connectors/connectors/codex/parsers.js

@@ -62,7 +62,9 @@ export function parseFrontmatter(text) {
 export function isRolloutFile(name) {
     return name.startsWith("rollout-") && name.endsWith(".jsonl");
 }
-export function buildThreadSessionRecord(id, t, agg) {
+export function buildThreadSessionRecord(id, t, agg, priorFingerprint) {
+    const messageCount = agg?.messageCount ?? priorFingerprint?.message_count ?? null;
+    const functionCallCount = agg?.functionCallCount ?? priorFingerprint?.function_call_count ?? null;
     return {
         id,
         cwd: t.cwd || null,
@@ -74,8 +76,8 @@ export function buildThreadSessionRecord(id, t, agg) {
         repository_url: t.git_origin_url || null,
         started_at: epochToIso(t.created_at) || agg?.meta?.timestamp || agg?.firstTs || null,
         last_event_at: epochToIso(t.updated_at) || agg?.lastTs || null,
-        message_count: agg?.messageCount ?? null,
-        function_call_count: agg?.functionCallCount ?? null,
+        message_count: messageCount,
+        function_call_count: functionCallCount,
         title: textPreview(t.title || null, 500),
         archived: t.archived === 1 || t.archived === true,
         tokens_used: t.tokens_used ?? null,

package/dist/polyfill-connectors/src/bounded-file-preview.js

@@ -0,0 +1,76 @@
+import { createReadStream } from "node:fs";
+export const BOUNDED_PREVIEW_MAX_BYTES = 64 * 1024;
+function trailingIncompleteUtf8Bytes(buf) {
+    let i = buf.length - 1;
+    let continuation = 0;
+    while (i >= 0) {
+        const byte = buf[i];
+        if (byte === undefined || (byte & 0b1100_0000) !== 0b1000_0000) {
+            break;
+        }
+        continuation++;
+        i--;
+        if (continuation > 3) {
+            return 0;
+        }
+    }
+    const lead = i >= 0 ? buf[i] : undefined;
+    if (lead === undefined) {
+        return 0;
+    }
+    let expected;
+    if ((lead & 0b1000_0000) === 0) {
+        expected = 1;
+    }
+    else if ((lead & 0b1110_0000) === 0b1100_0000) {
+        expected = 2;
+    }
+    else if ((lead & 0b1111_0000) === 0b1110_0000) {
+        expected = 3;
+    }
+    else if ((lead & 0b1111_1000) === 0b1111_0000) {
+        expected = 4;
+    }
+    else {
+        return 0;
+    }
+    const have = continuation + 1;
+    return have < expected ? have : 0;
+}
+export async function readBoundedFilePreview(path, maxBytes = BOUNDED_PREVIEW_MAX_BYTES) {
+    if (maxBytes <= 0) {
+        return { buffer: Buffer.alloc(0), bytesRead: 0, truncated: false };
+    }
+    return await new Promise((resolve) => {
+        const chunks = [];
+        let collected = 0;
+        let sawMore = false;
+        const stream = createReadStream(path, { start: 0, end: maxBytes });
+        stream.on("data", (chunk) => {
+            const buf = chunk;
+            const remaining = maxBytes - collected;
+            if (remaining <= 0) {
+                sawMore = true;
+                return;
+            }
+            if (buf.length > remaining) {
+                chunks.push(buf.subarray(0, remaining));
+                collected += remaining;
+                sawMore = true;
+            }
+            else {
+                chunks.push(buf);
+                collected += buf.length;
+            }
+        });
+        stream.on("error", () => resolve(null));
+        stream.on("end", () => {
+            let buffer = chunks.length === 1 && chunks[0] ? chunks[0] : Buffer.concat(chunks, collected);
+            const trim = trailingIncompleteUtf8Bytes(buffer);
+            if (trim > 0) {
+                buffer = buffer.subarray(0, buffer.length - trim);
+            }
+            resolve({ buffer, bytesRead: buffer.length, truncated: sawMore });
+        });
+    });
+}

package/dist/polyfill-connectors/src/browser-handoff.js

@@ -19,6 +19,7 @@ const BROWSER_SURFACE_ID_ENV = "PDPP_BROWSER_SURFACE_ID";
 const BROWSER_SURFACE_LEASE_ID_ENV = "PDPP_BROWSER_SURFACE_LEASE_ID";
 const BROWSER_SURFACE_PROFILE_KEY_ENV = "PDPP_BROWSER_SURFACE_PROFILE_KEY";
 const BROWSER_SURFACE_REQUIRED_ENV = "PDPP_BROWSER_SURFACE_REQUIRED";
+const BROWSER_SURFACE_REMOTE_CDP_URL_ENV = "PDPP_BROWSER_SURFACE_REMOTE_CDP_URL";
 const BROWSER_SURFACE_STREAM_BASE_URL_ENV = "PDPP_BROWSER_SURFACE_STREAM_BASE_URL";
 function resolveCdpEndpointFromEnv(env) {
     const host = env[BROWSER_CDP_HOST_ENV]?.trim();
@@ -43,12 +44,14 @@ function resolveManagedNekoDescriptorFromEnv(env) {
     const baseUrl = nonEmptyEnv(env, BROWSER_SURFACE_STREAM_BASE_URL_ENV);
     const leaseId = nonEmptyEnv(env, BROWSER_SURFACE_LEASE_ID_ENV);
     const profileKey = nonEmptyEnv(env, BROWSER_SURFACE_PROFILE_KEY_ENV);
+    const cdpHttpUrl = nonEmptyEnv(env, BROWSER_SURFACE_REMOTE_CDP_URL_ENV);
     if (!(baseUrl && leaseId && profileKey)) {
         return;
     }
     return {
         backend: "neko",
         base_url: baseUrl,
+        ...(cdpHttpUrl ? { cdp_http_url: cdpHttpUrl } : {}),
         lease_id: leaseId,
         profile_key: profileKey,
         ...(nonEmptyEnv(env, BROWSER_SURFACE_ID_ENV) ? { surface_id: nonEmptyEnv(env, BROWSER_SURFACE_ID_ENV) } : {}),
@@ -57,7 +60,29 @@ function resolveManagedNekoDescriptorFromEnv(env) {
 function generateInteractionId() {
     return `int_${String(Date.now())}_${randomBytes(4).toString("hex")}`;
 }
-async function readManualActionPageMetadata(page) {
+export const DEADLINE_TIMEOUT = Symbol("pdpp.browser-handoff.deadline-timeout");
+const DEFAULT_METADATA_READ_DEADLINE_MS = 2000;
+export async function withDeadline(work, ms, onTimeout) {
+    if (!(Number.isFinite(ms) && ms > 0)) {
+        return work;
+    }
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            onTimeout?.();
+            resolve(DEADLINE_TIMEOUT);
+        }, ms);
+    });
+    try {
+        return await Promise.race([work, deadline]);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}
+async function readManualActionPageMetadata(page, deadlineMs = DEFAULT_METADATA_READ_DEADLINE_MS) {
     let pageUrl;
     let pageTitle;
     try {
@@ -66,7 +91,12 @@ async function readManualActionPageMetadata(page) {
     catch {
     }
     try {
-        pageTitle = await page.title();
+        const titleResult = await withDeadline(page.title(), deadlineMs, () => {
+            process.stderr.write(`[browser-handoff] page.title() timed out after ${String(deadlineMs)}ms; emitting interaction without page title.\n`);
+        });
+        if (titleResult !== DEADLINE_TIMEOUT) {
+            pageTitle = titleResult;
+        }
     }
     catch {
     }
@@ -115,11 +145,11 @@ function registerCdpManualActionTarget(args) {
         ...(args.reason ? { reason: args.reason } : {}),
     });
 }
-export async function prepareManualAction(args) {
+export async function prepareBrowserInteractionTarget(args) {
     const env = args.env ?? process.env;
     const resolveStreamingRegistration = args.resolveStreamingRegistration ?? resolveStreamingRegistrationFromEnv;
     const resolveWsUrl = args.resolveWsUrl ?? resolveWsUrlForExactPage;
-    const interactionId = generateInteractionId();
+    const interactionId = args.interactionId ?? generateInteractionId();
     const registration = await resolveStreamingRegistration(env);
     if (!registration) {
         return { interactionId, registered: false };
@@ -161,6 +191,9 @@ export async function prepareManualAction(args) {
     }
     return { interactionId, registered: true };
 }
+export function prepareManualAction(args) {
+    return prepareBrowserInteractionTarget(args);
+}
 function captureManualActionFixture(args) {
     if (!args.capture) {
         return;
@@ -194,4 +227,4 @@ export async function manualAction(args, sendInteraction) {
         ...(args.timeoutSeconds === undefined ? {} : { timeout_seconds: args.timeoutSeconds }),
     });
 }
-export { BROWSER_CDP_HOST_ENV, BROWSER_CDP_PORT_ENV, BROWSER_SURFACE_ID_ENV, BROWSER_SURFACE_LEASE_ID_ENV, BROWSER_SURFACE_PROFILE_KEY_ENV, BROWSER_SURFACE_REQUIRED_ENV, BROWSER_SURFACE_STREAM_BASE_URL_ENV, };
+export { BROWSER_CDP_HOST_ENV, BROWSER_CDP_PORT_ENV, BROWSER_SURFACE_ID_ENV, BROWSER_SURFACE_LEASE_ID_ENV, BROWSER_SURFACE_PROFILE_KEY_ENV, BROWSER_SURFACE_REMOTE_CDP_URL_ENV, BROWSER_SURFACE_REQUIRED_ENV, BROWSER_SURFACE_STREAM_BASE_URL_ENV, };

package/dist/polyfill-connectors/src/collector-build-info.d.ts

@@ -0,0 +1,8 @@
+export declare const COLLECTOR_BUILD_SOURCE_SENTINEL = "source";
+export interface CollectorBuildInfo {
+    builtAt: string | null;
+    revision: string;
+    version: string;
+}
+export declare const COLLECTOR_BUILD_INFO: CollectorBuildInfo;
+export declare function buildAgentVersion(info?: CollectorBuildInfo): string;

package/dist/polyfill-connectors/src/collector-build-info.js

@@ -0,0 +1,10 @@
+const COLLECTOR_BUILD_SOURCE_SENTINEL = "source";
+const COLLECTOR_BUILD_INFO = {
+    builtAt: "2026-06-10T20:53:47.540Z",
+    revision: "f9fdc632c3b0",
+    version: "0.1.0-beta.8",
+};
+function buildAgentVersion(info = COLLECTOR_BUILD_INFO) {
+    return `${info.version}+${info.revision}`;
+}
+export { COLLECTOR_BUILD_INFO, COLLECTOR_BUILD_SOURCE_SENTINEL, buildAgentVersion };

package/dist/polyfill-connectors/src/collector-runner.d.ts

@@ -16,6 +16,38 @@ export interface CollectorOutboxPolicy {
     retryBackoffMs: number;
 }
 export declare const DEFAULT_COLLECTOR_OUTBOX_POLICY: Readonly<CollectorOutboxPolicy>;
+export interface CollectorAutoPrunePolicy {
+    enabled: boolean;
+    keepRecentCount: number;
+}
+export declare const DEFAULT_COLLECTOR_AUTO_PRUNE_POLICY: Readonly<CollectorAutoPrunePolicy>;
+export declare function resolveCollectorAutoPrunePolicy(override?: Partial<CollectorAutoPrunePolicy>, env?: NodeJS.ProcessEnv): CollectorAutoPrunePolicy;
+export declare function autoPruneSucceededOutbox(input: {
+    outbox: Pick<LocalDeviceOutbox, "pruneSent">;
+    policy: CollectorAutoPrunePolicy;
+    sourceInstanceId: string;
+}): CollectorAutoPruneResult;
+export interface CollectorAutoPruneResult {
+    enabled: boolean;
+    matched: number;
+    pruned: number;
+}
+export interface CollectorAutoCompactPolicy {
+    enabled: boolean;
+    minReclaimableBytes: number;
+}
+export declare const DEFAULT_COLLECTOR_AUTO_COMPACT_POLICY: Readonly<CollectorAutoCompactPolicy>;
+export declare function resolveCollectorAutoCompactPolicy(override?: Partial<CollectorAutoCompactPolicy>, env?: NodeJS.ProcessEnv): CollectorAutoCompactPolicy;
+export declare function autoCompactOutboxIfBloated(input: {
+    outbox: Pick<LocalDeviceOutbox, "compact" | "countNonSucceeded" | "pageStats">;
+    policy: CollectorAutoCompactPolicy;
+}): CollectorAutoCompactResult;
+export interface CollectorAutoCompactResult {
+    compacted: boolean;
+    enabled: boolean;
+    reason: "disabled" | "below_threshold" | "lane_not_quiet" | "compacted";
+    reclaimedBytes: number;
+}
 export interface CollectorEnrollmentConfig {
     baseUrl: string;
     code: string;
@@ -32,6 +64,8 @@ export interface CollectorConnectorSpec extends ConnectorPlacementInput {
 }
 export interface CollectorRunConfig {
     abortSignal?: AbortSignal;
+    autoCompact?: Partial<CollectorAutoCompactPolicy>;
+    autoPrune?: Partial<CollectorAutoPrunePolicy>;
     baseUrl: string;
     batchSize?: number;
     collectorHolderId?: string;
@@ -44,7 +78,17 @@ export interface CollectorRunConfig {
     runId?: string;
     sourceInstanceId: string;
 }
+export declare const COLLECTOR_COVERAGE_STATUSES: readonly ["collected", "inventory_only", "excluded", "deferred", "missing", "unsupported", "unaccounted"];
+export type CollectorCoverageStatus = (typeof COLLECTOR_COVERAGE_STATUSES)[number];
+export interface CollectorCompletenessSummary {
+    byStore: Readonly<Record<string, CollectorCoverageStatus>>;
+    countsByStatus: Readonly<Record<CollectorCoverageStatus, number>>;
+    fullyAccounted: boolean;
+    storeCount: number;
+    unaccountedStores: readonly string[];
+}
 export interface CollectorRunResult {
+    completeness: CollectorCompletenessSummary | null;
     done: Extract<EmittedMessage, {
         type: "DONE";
     }> | null;
@@ -52,6 +96,7 @@ export interface CollectorRunResult {
     flushedState: Readonly<Record<string, unknown>> | null;
     outboxSummary: LocalDeviceOutboxSummary;
     priorState: Readonly<Record<string, unknown>>;
+    prunedSent: CollectorAutoPruneResult;
     recordsQueued: number;
     recoveredLeases: number;
     satisfiedBindings: readonly RuntimeBindingName[];
@@ -65,6 +110,7 @@ export declare class CollectorStateReadError extends Error {
     constructor(message: string, cause: unknown);
 }
 export declare function runCollectorConnector(config: CollectorRunConfig): Promise<CollectorRunResult>;
+export declare function summarizeCollectorCompleteness(coverageByStore: Map<string, CollectorCoverageStatus> | null): CollectorCompletenessSummary | null;
 export declare function buildCollectorStartMessage(streams: readonly string[], streamsToBackfill?: readonly string[], priorState?: Readonly<Record<string, unknown>> | null): StartMessage;
 export declare function transformRecordsToCollectorEnvelopes(input: {
     batchId: string;
@@ -118,6 +164,14 @@ export interface DrainCollectorOutboxResult {
     sentByKind: Readonly<Partial<Record<LocalDeviceOutboxItem["kind"], number>>>;
 }
 export declare function drainCollectorOutbox(input: DrainCollectorOutboxInput): Promise<DrainCollectorOutboxResult>;
+export declare const LOCAL_COLLECTOR_LIFECYCLE_STATES: readonly ["healthy_idle", "draining", "retryable_backlog", "dead_letter", "stale_lease", "coverage_missing"];
+export type LocalCollectorLifecycleState = (typeof LOCAL_COLLECTOR_LIFECYCLE_STATES)[number];
+export interface LocalCollectorLifecycleInput {
+    coverageObserved: boolean | null;
+    recordBatchCount: number;
+    summary: LocalDeviceOutboxSummary;
+}
+export declare function deriveLocalCollectorLifecycleState(input: LocalCollectorLifecycleInput): LocalCollectorLifecycleState;
 export declare function buildHeartbeatOutboxDiagnostics(summary: LocalDeviceOutboxSummary, options?: {
     backlogOpen?: number;
 }): HeartbeatOutboxDiagnostics;