@google/jules-merge 0.0.1

package/dist/core/src/snapshot.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Activity, PullRequest, SessionInsights, SessionResource, SessionSnapshot, SessionState, SerializedSnapshot, TimelineEntry, GeneratedFiles, ChangeSet, ToJSONOptions } from './types.js';
+export interface SessionSnapshotOptions {
+    data: {
+        session: SessionResource;
+        activities?: Activity[];
+    };
+}
+export declare class SessionSnapshotImpl implements SessionSnapshot {
+    readonly id: string;
+    readonly state: SessionState;
+    readonly url: string;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+    readonly durationMs: number;
+    readonly prompt: string;
+    readonly title: string;
+    readonly pr?: PullRequest;
+    readonly activities: readonly Activity[];
+    readonly activityCounts: Readonly<Record<string, number>>;
+    readonly timeline: readonly TimelineEntry[];
+    readonly insights: SessionInsights;
+    readonly generatedFiles: GeneratedFiles;
+    readonly changeSet: () => ChangeSet | undefined;
+    constructor(options: SessionSnapshotOptions);
+    private computeActivityCounts;
+    private computeTimeline;
+    private generateSummary;
+    private computeInsights;
+    toJSON(options?: ToJSONOptions): Partial<SerializedSnapshot>;
+    toMarkdown(): string;
+}

package/dist/core/src/sources.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ApiClient } from './api.js';
+import { SourceManager } from './types.js';
+/**
+ * Creates a SourceManager instance.
+ * The SourceManager is a callable object (an async iterator) with a `get` method attached.
+ * @internal
+ */
+export declare function createSourceManager(apiClient: ApiClient): SourceManager;

package/dist/core/src/storage/cache-info.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Activity } from '../types.js';
+/**
+ * Represents the cache information for a single session.
+ */
+export type SessionCacheInfo = {
+    sessionId: string;
+    activityCount: number;
+    lastSyncedAt: Date;
+};
+/**
+ * Represents global cache information.
+ */
+export type GlobalCacheInfo = {
+    lastSyncedAt: Date;
+    sessionCount: number;
+};
+/**
+ * Retrieves cache information for a specific session.
+ *
+ * @param sessionId - The ID of the session.
+ * @returns A promise that resolves with the session's cache information, or null if not found.
+ */
+export declare function getSessionCacheInfo(sessionId: string, rootDirOverride?: string): Promise<SessionCacheInfo | null>;
+export declare function updateGlobalCacheMetadata(rootDirOverride?: string): Promise<void>;
+export declare function getCacheInfo(rootDirOverride?: string): Promise<GlobalCacheInfo>;
+export declare function getSessionCount(rootDirOverride?: string): Promise<number>;
+export declare function getActivityCount(sessionId: string, rootDirOverride?: string): Promise<number>;
+export declare function getLatestActivities(sessionId: string, n: number, rootDirOverride?: string): Promise<Activity[]>;

package/dist/core/src/storage/memory.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Activity, SessionResource } from '../types.js';
+import { ActivityStorage, SessionStorage, CachedSession, SessionIndexEntry } from './types.js';
+/**
+ * In-memory implementation of ActivityStorage.
+ * Useful for testing or environments where persistence is not required.
+ */
+export declare class MemoryStorage implements ActivityStorage {
+    private activities;
+    private indices;
+    /**
+     * Initializes the storage. No-op for memory storage.
+     */
+    init(): Promise<void>;
+    /**
+     * Closes the storage and clears memory.
+     */
+    close(): Promise<void>;
+    /**
+     * Appends an activity to the in-memory list.
+     *
+     * **Guarantee:**
+     * - Idempotent: If an activity with the same ID exists, it updates it in place.
+     * - Append-only: New activities are always added to the end.
+     *
+     * **Side Effects:**
+     * - Modifies the internal `activities` array.
+     */
+    append(activity: Activity): Promise<void>;
+    /**
+     * Retrieves an activity by ID.
+     */
+    get(activityId: string): Promise<Activity | undefined>;
+    /**
+     * Retrieves the latest activity.
+     */
+    latest(): Promise<Activity | undefined>;
+    /**
+     * Yields all activities in chronological order.
+     */
+    scan(): AsyncIterable<Activity>;
+}
+/**
+ * In-memory implementation of SessionStorage.
+ */
+export declare class MemorySessionStorage implements SessionStorage {
+    private sessions;
+    private index;
+    init(): Promise<void>;
+    upsert(session: SessionResource): Promise<void>;
+    upsertMany(sessions: SessionResource[]): Promise<void>;
+    get(sessionId: string): Promise<CachedSession | undefined>;
+    delete(sessionId: string): Promise<void>;
+    scanIndex(): AsyncIterable<SessionIndexEntry>;
+}

package/dist/core/src/storage/node-fs.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Activity, SessionResource } from '../types.js';
+import { ActivityStorage, SessionStorage, CachedSession, SessionIndexEntry } from './types.js';
+/**
+ * Node.js filesystem implementation of ActivityStorage.
+ * Stores activities in a JSONL file located at `.jules/cache/<sessionId>/activities.jsonl`.
+ */
+export declare class NodeFileStorage implements ActivityStorage {
+    private filePath;
+    private metadataPath;
+    private initialized;
+    private writeStream;
+    private index;
+    private indexBuilt;
+    private indexBuildPromise;
+    private currentFileSize;
+    constructor(sessionId: string, rootDir: string);
+    /**
+     * Initializes the storage by ensuring the cache directory exists.
+     *
+     * **Side Effects:**
+     * - Creates the `.jules/cache/<sessionId>` directory if it does not exist.
+     * - Sets the internal `initialized` flag.
+     */
+    init(): Promise<void>;
+    /**
+     * Closes the storage.
+     */
+    close(): Promise<void>;
+    private _readMetadata;
+    private _writeMetadata;
+    /**
+     * Appends an activity to the file.
+     *
+     * **Side Effects:**
+     * - Appends a new line containing the JSON representation of the activity to `activities.jsonl`.
+     * - Implicitly calls `init()` if not already initialized.
+     */
+    append(activity: Activity): Promise<void>;
+    /**
+     * Builds the in-memory index by scanning the file once.
+     * Handles concurrency by coalescing multiple calls into a single promise.
+     */
+    private buildIndex;
+    /**
+     * Retrieves an activity by ID.
+     * Uses an in-memory index (ID -> Offset) to seek directly to the line.
+     */
+    get(activityId: string): Promise<Activity | undefined>;
+    /**
+     * Retrieves the latest activity.
+     * Efficiently reads the file backwards to find the last valid entry.
+     */
+    latest(): Promise<Activity | undefined>;
+    /**
+     * Yields all activities in the file.
+     *
+     * **Behavior:**
+     * - Opens a read stream to `activities.jsonl`.
+     * - Reads line-by-line using `readline`.
+     * - Parses each line as JSON.
+     *
+     * **Edge Cases:**
+     * - Logs a warning and skips lines if JSON parsing fails (corrupt data).
+     * - Returns immediately (yields nothing) if the file does not exist.
+     */
+    scan(): AsyncIterable<Activity>;
+}
+export declare class NodeSessionStorage implements SessionStorage {
+    private cacheDir;
+    private indexFilePath;
+    private initialized;
+    constructor(rootDir: string);
+    init(): Promise<void>;
+    private getSessionPath;
+    upsert(session: SessionResource): Promise<void>;
+    upsertMany(sessions: SessionResource[]): Promise<void>;
+    get(sessionId: string): Promise<CachedSession | undefined>;
+    delete(sessionId: string): Promise<void>;
+    scanIndex(): AsyncIterable<SessionIndexEntry>;
+}

package/dist/core/src/storage/root.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export declare function isWritable(dir: string): boolean;
+export declare function getRootDir(): string;

package/dist/core/src/storage/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Activity, SessionResource } from '../types.js';
+/**
+ * Represents the wrapper around the raw resource, adding local metadata.
+ */
+export type CachedSession = {
+    resource: SessionResource;
+    _lastSyncedAt: number;
+};
+/**
+ * Subset of session fields required for the high-speed index.
+ * These are the fields we can filter on without opening the heavy session file.
+ */
+export type SessionIndexEntry = {
+    id: string;
+    title: string;
+    state: string;
+    createTime: string;
+    source: string;
+    _updatedAt: number;
+};
+/**
+ * Ephemeral (but persisted) metadata about a session's cache state.
+ * Stored separately from the main session.json to allow for frequent updates
+ * without rewriting the larger session object.
+ */
+export type SessionMetadata = {
+    activityCount: number;
+};
+export interface SessionStorage {
+    /**
+     * Initializes the storage (ensure directories exist).
+     */
+    init(): Promise<void>;
+    /**
+     * Persists a session state.
+     * 1. Writes the full resource to atomic storage (.jules/cache/<id>/session.json).
+     * 2. Appends metadata to the high-speed index (.jules/cache/sessions.jsonl).
+     */
+    upsert(session: SessionResource): Promise<void>;
+    /**
+     * Bulk optimization for upserting pages from the API.
+     */
+    upsertMany(sessions: SessionResource[]): Promise<void>;
+    /**
+     * Retrieves a specific session by ID.
+     * Returns undefined if not found or if the file is corrupt.
+     */
+    get(sessionId: string): Promise<CachedSession | undefined>;
+    /**
+     * Deletes a session and its associated artifacts from local cache.
+     */
+    delete(sessionId: string): Promise<void>;
+    /**
+     * Scans the high-speed index.
+     * Implementation MUST handle deduplication (Last-Write-Wins) because the
+     * index is an append-only log.
+     */
+    scanIndex(): AsyncIterable<SessionIndexEntry>;
+}
+/**
+ * Abstract interface for the isomorphic storage layer.
+ * Implementations handle the specifics of persisting immutable activities
+ * to the available medium (Filesystem, IndexedDB, Memory, etc.).
+ */
+export interface ActivityStorage {
+    /**
+     * Lifecycle method to initialize the storage (e.g., open DB connection, ensure storage directory exists).
+     * Must be called before any other method.
+     */
+    init(): Promise<void>;
+    /**
+     * Lifecycle method to close connections or flush buffers.
+     */
+    close(): Promise<void>;
+    /**
+     * Persists a single activity.
+     * Implementations MUST guarantee this is an append-only operation (or upsert if ID matches).
+     * It should NEVER delete or modify a different activity.
+     */
+    append(activity: Activity): Promise<void>;
+    /**
+     * Retrieves a specific activity by its ID.
+     * @returns The activity if found, or undefined.
+     */
+    get(activityId: string): Promise<Activity | undefined>;
+    /**
+     * Retrieves the most recently appended activity.
+     * Crucial for determining the high-water mark for network synchronization.
+     */
+    latest(): Promise<Activity | undefined>;
+    /**
+     * Yields all stored activities in chronological order (insertion order).
+     * Must support standard 'for await...of' loops.
+     */
+    scan(): AsyncIterable<Activity>;
+}
+export interface GlobalCacheMetadata {
+    lastSyncedAt: number;
+    sessionCount: number;
+}

package/dist/core/src/streaming.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ApiClient } from './api.js';
+import { Activity, Origin } from './types.js';
+/**
+ * Options for controlling the activity stream.
+ * @internal
+ */
+export type StreamActivitiesOptions = {
+    /**
+     * Filters to exclude certain activities.
+     */
+    exclude?: {
+        originator: Origin;
+    };
+    /**
+     * Number of retries for initial 404 errors when session is not yet ready.
+     * @default 10
+     */
+    initialRetries?: number;
+};
+/**
+ * An async generator that implements a hybrid pagination/polling strategy
+ * to stream activities for a given session.
+ *
+ * @param sessionId The ID of the session to stream activities for.
+ * @param apiClient The API client to use for requests.
+ * @param pollingInterval The time in milliseconds to wait before polling for new activities.
+ * @param platform The platform adapter.
+ * @param options Streaming options, including filters.
+ * @internal
+ */
+import { Platform } from './platform/types.js';
+export declare function streamActivities(sessionId: string, apiClient: ApiClient, pollingInterval: number, platform: Platform, options?: StreamActivitiesOptions): AsyncGenerator<Activity>;