@phigon/observer 8.1.0 → 8.2.0

package/dist/src/activity/json-document-source.d.ts

@@ -0,0 +1,136 @@
+import type { SourceRecord } from "./source-reader.js";
+export type JSONDocumentOptions = Readonly<{
+    /**
+     * `json` (default): one JSON document. `jsonl`: one message per line; a
+     * final line that is still being written is read once it is complete.
+     * `mutation-log`: a VS Code chat session log (an initial state followed
+     * by set, push and delete entries) replayed into its document.
+     */
+    documentFormat?: "json" | "jsonl" | "mutation-log";
+    /**
+     * Regular expression matched against each directory's `/`-separated
+     * relative path. Only matching directories are walked.
+     */
+    directoryPattern?: string;
+    /** Dotted path of a stable id inside each message. */
+    messageIdField?: string;
+    /**
+     * Dotted fields that mark a message as finished. The last message is held
+     * back while it has none of them set, so a reply that is still being
+     * written is delivered once, complete. An earlier message is final even
+     * without them: the agent has moved on from it.
+     */
+    completeFields?: readonly string[];
+    /**
+     * Field that is true while a message is still being written (for example
+     * Cline's `partial`). The last message is held back while it is true.
+     */
+    pendingField?: string;
+    /**
+     * When set, the document's first message is delivered with this field set
+     * to true. Some agents store the user's opening request like any other
+     * message, so only its position tells it apart.
+     */
+    firstMessageField?: string;
+    /**
+     * Top-level field that holds the agent's own session id. When present it
+     * names the session and its records, so two files holding the same
+     * session produce the same record identities.
+     */
+    sessionIdField?: string;
+}>;
+export type JSONDocumentSource = Readonly<{
+    adapterId: string;
+    roots: readonly string[];
+    /** Regular expression matched against the `/`-separated relative path. */
+    pathPattern: string;
+    /**
+     * Top-level array that holds the conversation messages, or "" when the
+     * document itself is the array.
+     */
+    messagesField: string;
+}> & JSONDocumentOptions;
+type ScanOptions = Readonly<{
+    cursors: Map<string, number>;
+    /** Reused folder listings; without one every scan lists every folder. */
+    listings?: DirectoryListingCache;
+    initialScan: boolean;
+    replayOnFirstStart: boolean;
+    replaySessions: number;
+    maxReplayRecords: number;
+    maxRecords: number;
+    historical: boolean;
+}>;
+/**
+ * Reads agents that keep each conversation as one JSON document rewritten
+ * in place (for example `{ messages: [...] }`). A document's cursor holds
+ * the number of messages already delivered and a fingerprint of the last
+ * one, so new messages are emitted once although the whole file is
+ * rewritten. A document whose delivered prefix changed (compaction or a
+ * rewind) resumes after the remembered message, or is re-baselined when
+ * that message is gone. Unchanged documents are not parsed again.
+ */
+export declare function scanJSONDocumentSource(source: JSONDocumentSource, options: ScanOptions): Promise<Readonly<{
+    records: readonly SourceRecord[];
+    files: number;
+    malformed: number;
+    oversized: number;
+    complete: boolean;
+}>>;
+export declare function packCursor(messages: readonly unknown[], count: number, idField: string | undefined): number;
+/**
+ * Index of the first undelivered message. The delivered prefix must still
+ * end with the remembered message; if it moved, resume after it; if it is
+ * gone the document was rewritten and everything present is treated as
+ * already delivered.
+ */
+export declare function resumeIndex(messages: readonly unknown[], cursor: number, idField: string | undefined): number;
+type DirectoryEntry = Readonly<{
+    name: string;
+    directory: boolean;
+    file: boolean;
+}>;
+type ListingFileSystem = Readonly<{
+    readdir: (directory: string) => Promise<readonly DirectoryEntry[]>;
+    modifiedMs: (directory: string) => Promise<number>;
+    metadata: (file: string) => Promise<Readonly<{
+        modifiedMs: number;
+        size: number;
+    }>>;
+    now: () => number;
+}>;
+/**
+ * Folder listings reused across scans. Adding, removing or renaming an entry
+ * changes its folder's modified time, so a folder is listed again only when
+ * that time moved. Checking a folder costs about half of listing it, and
+ * most folders under an agent's session store never change. A folder that
+ * changed within the last two seconds is listed again on the next scan,
+ * because coarse file-system clocks can hide a second change in the same
+ * tick, and every folder is listed afresh at least every 30 seconds.
+ *
+ * Folders and documents untouched for ten minutes are cold: they are checked
+ * every ten seconds instead of on every scan, so a conversation resumed in a
+ * quiet project is noticed within ten seconds while active ones stay live.
+ */
+export declare class DirectoryListingCache {
+    #private;
+    static readonly relistAfterMs = 30000;
+    static readonly settleMs = 2000;
+    static readonly coldAfterMs: number;
+    static readonly coldCheckMs = 10000;
+    static readonly maxFolders = 8192;
+    constructor(fileSystem?: ListingFileSystem);
+    /**
+     * The folder's entries. `trustMs` skips even the folder check while the
+     * listing is younger than that; history imports use it, since live
+     * collection already follows new conversations.
+     */
+    list(directory: string, trustMs?: number): Promise<readonly DirectoryEntry[]>;
+    /** A document's time and size; a cold document is checked every ten seconds. */
+    metadata(file: string): Promise<Readonly<{
+        modifiedMs: number;
+        size: number;
+    }>>;
+}
+export {};
+//# sourceMappingURL=json-document-source.d.ts.map

package/dist/src/activity/json-document-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-document-source.d.ts","sourceRoot":"","sources":["../../../src/activity/json-document-source.ts"],"names":[],"mappings":"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"}