lark-remote 0.1.6 → 0.1.8

package/dist/session/common/jsonl.js

@@ -1,66 +1,135 @@
 import fs from 'node:fs';
 /**
- * Find the first line in a JSONL file that matches a predicate using streaming reads.
- * Stops reading as soon as a match is found.
+ * Stream a JSONL file line-by-line using chunked reads.
  *
- * @param filePath  Absolute path to a `.jsonl` file.
- * @param pred      Predicate applied to each trimmed non-empty line.
- * @returns The matching trimmed line, or null if no match / file not found / read error.
+ * Opens the file, reads in 64KB chunks, splits on `\n`, and invokes `onLine`
+ * for each non-empty trimmed line. Handles files without a trailing newline.
+ *
+ * `onLine` may return `true` to **stop early** (no further reads); the file
+ * descriptor is always closed in a `finally` block.
+ *
+ * @returns `true` if the file was opened and scanned, `false` on open error.
  */
-export function findJsonlLine(filePath, pred) {
+function forEachJsonlLine(filePath, onLine) {
+    return forEachJsonlLineCore(filePath, { onLine });
+}
+/**
+ * Variant of `forEachJsonlLine` that also tracks **byte offsets** for each line.
+ *
+ * `onLine` receives `(line, offset)` where `offset` is the starting byte offset
+ * of the line within the file. May return `true` to stop early.
+ *
+ * @returns `true` if the file was opened and scanned, `false` on open error.
+ */
+function forEachJsonlLineWithOffset(filePath, onLine) {
+    return forEachJsonlLineCore(filePath, {
+        onLine: (line, offset) => onLine(line, offset ?? 0),
+        trackOffsets: true,
+    });
+}
+/**
+ * Variant of `forEachJsonlLine` that starts reading from a byte `offset`.
+ *
+ * @param filePath Absolute path to a `.jsonl` file.
+ * @param offset   Byte offset to seek to before reading. **Must fall on a line
+ *                 boundary**; a mid-line offset will include a leading partial line.
+ * @param onLine   Called for each non-empty trimmed line. May return `true` to stop early.
+ * @returns `true` if the file was opened and scanned, `false` on open error.
+ */
+function forEachJsonlLineFromOffset(filePath, offset, onLine) {
+    if (offset < 0)
+        return false;
+    return forEachJsonlLineCore(filePath, { startOffset: offset, onLine });
+}
+/**
+ * Core chunked JSONL reader shared by the three public variants. Reads the
+ * file in 64KB chunks, splitting on `\n` at the byte level (UTF-8 multi-byte
+ * characters never contain 0x0A, so this never truncates a multi-byte seq).
+ *
+ * @param opts.startOffset   Byte offset to seek to before reading (0 = start).
+ * @param opts.trackOffsets  When true, pass each line's starting byte offset to onLine.
+ * @param opts.onLine        Called per non-empty trimmed line; may return `true` to stop.
+ */
+function forEachJsonlLineCore(filePath, opts) {
     let fd;
     try {
         fd = fs.openSync(filePath, 'r');
     }
     catch {
-        return null;
+        return false;
     }
-    const chunk = Buffer.alloc(65536);
+    const CHUNK_SIZE = 65536;
+    const chunk = Buffer.alloc(CHUNK_SIZE);
+    // Raw byte buffer holding the not-yet-decoded tail (everything after the
+    // last consumed `\n`). UTF-8 multi-byte characters never contain 0x0A,
+    // so splitting on `\n` at the byte level never truncates a multi-byte seq.
     let buf = Buffer.alloc(0);
+    let position = opts.startOffset ?? 0;
+    let baseOffset = 0;
+    let stop = false;
     try {
         for (;;) {
-            const n = fs.readSync(fd, chunk, 0, chunk.length, null);
-            if (n === 0)
+            const nread = fs.readSync(fd, chunk, 0, CHUNK_SIZE, position);
+            if (nread === 0)
                 break;
-            buf = Buffer.concat([buf, chunk.subarray(0, n)]);
-            // Find the last newline so we only decode complete lines. UTF-8 multi-byte
-            // characters never contain the 0x0A byte, so splitting on `\n` at the raw
-            // byte level is always safe and never truncates a multi-byte sequence.
+            buf = Buffer.concat([buf, chunk.subarray(0, nread)]);
             let nlIdx;
             while ((nlIdx = buf.lastIndexOf(0x0a)) !== -1) {
-                // Decode everything before the last `\n` and split into lines.
-                const text = buf.subarray(0, nlIdx).toString('utf-8');
-                // Keep the tail after the last `\n` as the new buffer.
+                const complete = buf.subarray(0, nlIdx);
+                const text = complete.toString('utf-8');
                 buf = buf.subarray(nlIdx + 1);
                 const parts = text.split('\n');
-                // All elements except the last are guaranteed complete (they had their
-                // own trailing `\n`). The last element is whatever followed the final
-                // `\n` in `text`; it may be empty or a partial line — re-emit it as part
-                // of the next buffer by prepending it back. But since we sliced on the
-                // *last* newline in buf, everything before it is fully complete lines
-                // joined by `\n`; the trailing fragment is already excluded by keeping
-                // only buf.subarray(nlIdx+1). So `parts` here is the complete lines,
-                // and `parts[parts.length-1]` is the final segment before the last `\n`
-                // — which IS complete (the last `\n` we split on was its terminator).
+                let cursor = (opts.startOffset ?? 0) + baseOffset;
                 for (const part of parts) {
                     const trimmed = part.trim();
-                    if (trimmed && pred(trimmed)) {
-                        return trimmed;
+                    if (trimmed) {
+                        if (opts.onLine(trimmed, opts.trackOffsets ? cursor : undefined) === true) {
+                            stop = true;
+                            break;
+                        }
                     }
+                    cursor += Buffer.byteLength(part, 'utf-8') + 1;
                 }
-                break;
+                baseOffset += complete.length + 1;
+                break; // only process up to last complete newline per chunk
             }
+            if (stop)
+                break;
+            position += nread;
         }
-        // Handle last remaining line (file without trailing newline).
-        const trimmed = buf.toString('utf-8').trim();
-        if (trimmed && pred(trimmed)) {
-            return trimmed;
+        // Handle remaining tail (file without trailing newline).
+        if (!stop) {
+            const tail = buf.toString('utf-8').trim();
+            if (tail) {
+                opts.onLine(tail, opts.trackOffsets ? (opts.startOffset ?? 0) + baseOffset : undefined);
+            }
         }
     }
     finally {
         fs.closeSync(fd);
     }
-    return null;
+    return true;
+}
+// ===========================================================================
+// Public API
+// ===========================================================================
+/**
+ * Find the first line in a JSONL file that matches a predicate using streaming reads.
+ * Stops reading as soon as a match is found.
+ *
+ * @param filePath  Absolute path to a `.jsonl` file.
+ * @param pred      Predicate applied to each trimmed non-empty line.
+ * @returns The matching trimmed line, or null if no match / file not found / read error.
+ */
+export function findJsonlLine(filePath, pred) {
+    let found = null;
+    forEachJsonlLine(filePath, (line) => {
+        if (pred(line)) {
+            found = line;
+            return true; // stop early
+        }
+    });
+    return found;
 }
 /**
  * Read the last non-empty line from a JSONL file using streaming reads.
@@ -69,58 +138,17 @@ export function findJsonlLine(filePath, pred) {
  * @returns The last trimmed non-empty line, or null if the file is empty / not found.
  */
 export function readLastJsonlLine(filePath) {
-    let fd;
-    try {
-        fd = fs.openSync(filePath, 'r');
-    }
-    catch {
-        return null;
-    }
-    const chunk = Buffer.alloc(65536);
-    let buf = Buffer.alloc(0);
     let last = null;
-    try {
-        for (;;) {
-            const n = fs.readSync(fd, chunk, 0, chunk.length, null);
-            if (n === 0)
-                break;
-            buf = Buffer.concat([buf, chunk.subarray(0, n)]);
-            let nlIdx;
-            while ((nlIdx = buf.lastIndexOf(0x0a)) !== -1) {
-                const text = buf.subarray(0, nlIdx).toString('utf-8');
-                buf = buf.subarray(nlIdx + 1);
-                const parts = text.split('\n');
-                for (const part of parts) {
-                    const trimmed = part.trim();
-                    if (trimmed) {
-                        last = trimmed;
-                    }
-                }
-                break;
-            }
-        }
-        const trimmed = buf.toString('utf-8').trim();
-        if (trimmed) {
-            last = trimmed;
-        }
-    }
-    finally {
-        fs.closeSync(fd);
-    }
+    forEachJsonlLine(filePath, (line) => {
+        last = line;
+    });
     return last;
 }
 /**
  * Read the last N non-empty lines from a JSONL file using streaming reads.
  *
  * Unlike `readJsonlLines` (which materializes the entire file into a `string[]`),
- * this only retains the last `n` lines — memory is O(n), not O(whole file). The
- * file is still read front-to-back in chunks (no reverse seek), but earlier
- * lines are discarded as soon as the buffer exceeds `n`, so a multi-MB file
- * costs only ~`n` line strings of resident memory.
- *
- * Used by tail-only read paths (P2-5) such as `isSessionActive`, which only
- * need to inspect the file's tail (e.g. the last ~20 loop events) but were
- * previously full-slurping the whole wire log.
+ * this only retains the last `n` lines — memory is O(n), not O(whole file).
  *
  * @param filePath  Absolute path to a `.jsonl` file.
  * @param n         Maximum number of trailing non-empty lines to retain.
@@ -130,222 +158,59 @@ export function readLastJsonlLine(filePath) {
 export function readLastNJsonlLines(filePath, n) {
     if (n <= 0)
         return [];
-    let fd;
-    try {
-        fd = fs.openSync(filePath, 'r');
-    }
-    catch {
-        return [];
-    }
-    const chunk = Buffer.alloc(65536);
-    let buf = Buffer.alloc(0);
     const lines = [];
-    try {
-        for (;;) {
-            const nread = fs.readSync(fd, chunk, 0, chunk.length, null);
-            if (nread === 0)
-                break;
-            buf = Buffer.concat([buf, chunk.subarray(0, nread)]);
-            let nlIdx;
-            while ((nlIdx = buf.lastIndexOf(0x0a)) !== -1) {
-                const text = buf.subarray(0, nlIdx).toString('utf-8');
-                buf = buf.subarray(nlIdx + 1);
-                const parts = text.split('\n');
-                for (const part of parts) {
-                    if (part.trim()) {
-                        lines.push(part);
-                        if (lines.length > n) {
-                            lines.splice(0, lines.length - n);
-                        }
-                    }
-                }
-                break;
-            }
+    forEachJsonlLine(filePath, (line) => {
+        lines.push(line);
+        if (lines.length > n) {
+            lines.splice(0, lines.length - n);
         }
-        const tail = buf.toString('utf-8');
-        if (tail.trim()) {
-            lines.push(tail);
-            if (lines.length > n) {
-                lines.splice(0, lines.length - n);
-            }
-        }
-    }
-    finally {
-        fs.closeSync(fd);
-    }
+    });
     return lines;
 }
 /**
  * Stream-scan a JSONL file once, invoking `onLine` for each non-empty line
  * with the line's raw string and its **starting byte offset** within the file.
  *
- * Unlike `readJsonlLines` this retains NOTHING — memory is O(chunk), not
- * O(whole file). The callback receives the byte offset so callers can record
- * where a line of interest (e.g. the last user message) begins, then re-read
- * only the tail from that offset via `readJsonlLinesFromOffset` (P2-5
- * byte-offset two-pass: full-file scalar scan without materializing a
- * `string[]`, then tail-only re-parse for events).
+ * Memory is O(chunk), not O(whole file). The callback receives the byte offset
+ * so callers can record where a line of interest begins, then re-read only the
+ * tail from that offset via `readJsonlLinesFromOffset`.
  *
  * @param filePath Absolute path to a `.jsonl` file.
- * @param onLine   Called for each non-empty line with `(line, offset)` where
- *                 `offset` is the byte offset of the line's first character.
+ * @param onLine   Called for each non-empty line with `(line, offset)`.
  * @returns `true` if the file was opened and scanned, `false` on open error.
  */
 export function scanJsonlLines(filePath, onLine) {
-    let fd;
-    try {
-        fd = fs.openSync(filePath, 'r');
-    }
-    catch {
-        return false;
-    }
-    const chunk = Buffer.alloc(65536);
-    // Raw byte buffer holding the not-yet-decoded tail (everything after the
-    // last consumed `\n`). Byte offsets are tracked against the real file, so
-    // they are immune to multi-byte UTF-8 decode artifacts.
-    let buf = Buffer.alloc(0);
-    let baseOffset = 0;
-    try {
-        for (;;) {
-            const nread = fs.readSync(fd, chunk, 0, chunk.length, null);
-            if (nread === 0)
-                break;
-            buf = Buffer.concat([buf, chunk.subarray(0, nread)]);
-            // Decode all complete lines (everything up to the last `\n`). The tail
-            // after the last `\n` stays in `buf` for the next iteration.
-            let nlIdx;
-            while ((nlIdx = buf.lastIndexOf(0x0a)) !== -1) {
-                const complete = buf.subarray(0, nlIdx);
-                const text = complete.toString('utf-8');
-                buf = buf.subarray(nlIdx + 1);
-                const parts = text.split('\n');
-                let cursor = baseOffset;
-                for (const part of parts) {
-                    if (part.trim()) {
-                        onLine(part, cursor);
-                    }
-                    // advance past this line + its '\n' (1 byte)
-                    cursor += Buffer.byteLength(part, 'utf-8') + 1;
-                }
-                baseOffset += complete.length + 1;
-                break;
-            }
-        }
-        const tail = buf.toString('utf-8');
-        if (tail.trim()) {
-            onLine(tail, baseOffset);
-        }
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-    return true;
+    return forEachJsonlLineWithOffset(filePath, onLine);
 }
 /**
  * Read all non-empty lines starting from a byte `offset` in a JSONL file.
  *
- * Companion to `scanJsonlLines` for the P2-5 byte-offset two-pass pattern:
- * pass 1 records the offset where the tail begins (e.g. the byte right after
- * the last user message); pass 2 seeks there and reads/parses only the tail,
- * so raw line-string memory is O(tail) instead of O(whole file).
+ * Companion to `scanJsonlLines` for the byte-offset two-pass pattern.
  *
  * @param filePath Absolute path to a `.jsonl` file.
  * @param offset   Byte offset to seek to before reading. **Must fall on a line
- *                 boundary** (e.g. 0, or the start of the line after the last
- *                 user message as recorded by `scanJsonlLines`); a mid-line
- *                 offset will include a leading partial line.
+ *                 boundary**; a mid-line offset will include a leading partial line.
  * @returns Array of raw line strings from `offset` to EOF (empty lines
  *          excluded). Empty array on open/seek error or `offset` past EOF.
  */
 export function readJsonlLinesFromOffset(filePath, offset) {
-    if (offset < 0)
-        return [];
-    let fd;
-    try {
-        fd = fs.openSync(filePath, 'r');
-    }
-    catch {
-        return [];
-    }
-    const chunk = Buffer.alloc(65536);
-    let buf = Buffer.alloc(0);
     const lines = [];
-    try {
-        let position = offset;
-        for (;;) {
-            const nread = fs.readSync(fd, chunk, 0, chunk.length, position);
-            if (nread === 0)
-                break;
-            buf = Buffer.concat([buf, chunk.subarray(0, nread)]);
-            let nlIdx;
-            while ((nlIdx = buf.lastIndexOf(0x0a)) !== -1) {
-                const text = buf.subarray(0, nlIdx).toString('utf-8');
-                buf = buf.subarray(nlIdx + 1);
-                const parts = text.split('\n');
-                for (const part of parts) {
-                    if (part.trim()) {
-                        lines.push(part);
-                    }
-                }
-                break;
-            }
-            position += nread;
-        }
-        const tail = buf.toString('utf-8');
-        if (tail.trim()) {
-            lines.push(tail);
-        }
-    }
-    finally {
-        fs.closeSync(fd);
-    }
+    forEachJsonlLineFromOffset(filePath, offset, (line) => {
+        lines.push(line);
+    });
     return lines;
 }
 /**
  * Read all non-empty lines from a JSONL file using streaming reads.
  *
  * @param filePath  Absolute path to a `.jsonl` file.
- * @param chunkSize Buffer size for each `fs.readSync` call (default 65536).
  * @returns Array of raw line strings (empty lines excluded).
  */
-export function readJsonlLines(filePath, chunkSize = 65536) {
-    let fd;
-    try {
-        fd = fs.openSync(filePath, 'r');
-    }
-    catch {
-        return [];
-    }
-    const chunk = Buffer.alloc(chunkSize);
-    let buf = Buffer.alloc(0);
+export function readJsonlLines(filePath) {
     const lines = [];
-    try {
-        for (;;) {
-            const n = fs.readSync(fd, chunk, 0, chunk.length, null);
-            if (n === 0)
-                break;
-            buf = Buffer.concat([buf, chunk.subarray(0, n)]);
-            let nlIdx;
-            while ((nlIdx = buf.lastIndexOf(0x0a)) !== -1) {
-                const text = buf.subarray(0, nlIdx).toString('utf-8');
-                buf = buf.subarray(nlIdx + 1);
-                const parts = text.split('\n');
-                for (const part of parts) {
-                    if (part.trim()) {
-                        lines.push(part);
-                    }
-                }
-                break;
-            }
-        }
-        const tail = buf.toString('utf-8');
-        if (tail.trim()) {
-            lines.push(tail);
-        }
-    }
-    finally {
-        fs.closeSync(fd);
-    }
+    forEachJsonlLine(filePath, (line) => {
+        lines.push(line);
+    });
     return lines;
 }
 //# sourceMappingURL=jsonl.js.map

package/dist/session/common/pagination.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared pagination / truncation helpers for agent session readers.
+ *
+ * The five readers (claude/codex/opencode/pi/kimi) all implement the same
+ * offset-clamp + slice + total pattern for `listSessions`, and the same
+ * maxEvents tail-cap for `readSessionContent`. These were duplicated (and had
+ * drifted on the default limit). Centralized here so the contract is defined
+ * once: default page limit is 20, matching the majority of readers.
+ */
+/** Default page size for listSessions. */
+export declare const DEFAULT_LIST_LIMIT = 20;
+/**
+ * Paginate a (already-ordered) full item list by offset + limit.
+ * Clamps negative offset to 0; caps limit to the remaining items.
+ */
+export declare function paginate<T>(items: T[], opts: {
+    limit?: number;
+    offset?: number;
+}): {
+    items: T[];
+    total: number;
+};
+/**
+ * Apply the maxEvents tail-cap shared by readSessionContent:
+ * keep the LAST N events; maxEvents <= 0 returns [] (guards the
+ * `slice(-0) === slice(0)` full-array trap).
+ */
+export declare function capEvents<T>(events: T[], maxEvents?: number): T[];

package/dist/session/common/pagination.js

@@ -0,0 +1,33 @@
+/**
+ * Shared pagination / truncation helpers for agent session readers.
+ *
+ * The five readers (claude/codex/opencode/pi/kimi) all implement the same
+ * offset-clamp + slice + total pattern for `listSessions`, and the same
+ * maxEvents tail-cap for `readSessionContent`. These were duplicated (and had
+ * drifted on the default limit). Centralized here so the contract is defined
+ * once: default page limit is 20, matching the majority of readers.
+ */
+/** Default page size for listSessions. */
+export const DEFAULT_LIST_LIMIT = 20;
+/**
+ * Paginate a (already-ordered) full item list by offset + limit.
+ * Clamps negative offset to 0; caps limit to the remaining items.
+ */
+export function paginate(items, opts) {
+    const limit = opts.limit ?? DEFAULT_LIST_LIMIT;
+    const offset = Math.max(0, opts.offset ?? 0);
+    return { items: items.slice(offset, offset + limit), total: items.length };
+}
+/**
+ * Apply the maxEvents tail-cap shared by readSessionContent:
+ * keep the LAST N events; maxEvents <= 0 returns [] (guards the
+ * `slice(-0) === slice(0)` full-array trap).
+ */
+export function capEvents(events, maxEvents) {
+    if (maxEvents === undefined || maxEvents > events.length)
+        return events;
+    if (maxEvents <= 0)
+        return [];
+    return events.slice(-maxEvents);
+}
+//# sourceMappingURL=pagination.js.map

package/dist/session/dsh/index.d.ts

@@ -0,0 +1 @@
+export { DshSessionReader } from './sessions.js';

package/dist/session/dsh/index.js

@@ -0,0 +1,2 @@
+export { DshSessionReader } from './sessions.js';
+//# sourceMappingURL=index.js.map

package/dist/session/dsh/sessions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * DshSessionReader — AgentSessionReader backed by the DSH Web Host over HTTP.
+ *
+ * The AgentSessionReader contract is fully synchronous (file-style readers),
+ * but DSH exposes only async HTTP. The reader therefore bridges with
+ * `spawnSync('curl', ...)` for its unary calls (session.list / session.history)
+ * — a synchronous HTTP round-trip to the local DSH host. This keeps the
+ * router/bridge interface contract intact without touching any upstream logic.
+ *
+ * listSessions: session.list → filter by cwd → sort by updatedAt desc → local
+ *   pagination (DSH v1 has no cursor pagination).
+ * readSessionContent: session.history → map SessionEvents to display events +
+ *   session-wide usage accumulation (assistant/message.usage).
+ */
+import type { AgentSession, AgentSessionReader, SessionContent } from '../../runner/index.js';
+interface DshSessionReaderOptions {
+    host?: string;
+    /** Injectable synchronous unary transport. Defaults to spawnSync curl. */
+    syncRequest?: (baseUrl: string, method: string, payload: unknown) => unknown;
+}
+export declare class DshSessionReader implements AgentSessionReader {
+    private readonly baseUrl;
+    private readonly syncRequest;
+    constructor(opts?: DshSessionReaderOptions);
+    private unary;
+    listSessions(cwd: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): {
+        sessions: AgentSession[];
+        total: number;
+    };
+    getNewestSession(cwd: string): AgentSession | null;
+    readSessionContent(sessionId: string, cwd: string, opts?: {
+        maxEvents?: number;
+    }): SessionContent;
+    isSessionActive(sessionId: string, cwd: string): boolean;
+}
+export {};