modjules 0.1.1

package/dist/client.d.ts

@@ -0,0 +1,112 @@
+import { JulesClient, JulesOptions, SessionConfig, SourceManager, AutomatedSession, SessionClient, StorageFactory } from './types.js';
+import { Platform } from './platform/types.js';
+/**
+ * The fully resolved internal configuration for the SDK.
+ * @internal
+ */
+export type InternalConfig = {
+    pollingIntervalMs: number;
+    requestTimeoutMs: number;
+};
+/**
+ * Implementation of the main JulesClient interface.
+ * This class acts as the central hub for creating and managing sessions,
+ * as well as accessing other resources like sources.
+ */
+export declare class JulesClientImpl implements JulesClient {
+    /**
+     * Manages source connections (e.g., GitHub repositories).
+     */
+    sources: SourceManager;
+    private apiClient;
+    private config;
+    private options;
+    private storageFactory;
+    private platform;
+    /**
+     * Creates a new instance of the JulesClient.
+     *
+     * @param options Configuration options for the client.
+     * @param defaultStorageFactory Factory for creating storage instances.
+     * @param defaultPlatform Platform-specific implementation.
+     */
+    constructor(options: JulesOptions | undefined, defaultStorageFactory: StorageFactory, defaultPlatform: Platform);
+    /**
+     * Creates a new Jules client instance with updated configuration.
+     * This is an immutable operation; the original client instance remains unchanged.
+     *
+     * @param options The new configuration options to merge with the existing ones.
+     * @returns A new JulesClient instance with the updated configuration.
+     */
+    with(options: JulesOptions): JulesClient;
+    all<T>(items: T[], mapper: (item: T) => SessionConfig | Promise<SessionConfig>, options?: {
+        concurrency?: number;
+        stopOnError?: boolean;
+        delayMs?: number;
+    }): Promise<AutomatedSession[]>;
+    private _prepareSessionCreation;
+    /**
+     * Executes a task in automated mode.
+     * This is a high-level abstraction for "fire-and-forget" tasks.
+     *
+     * **Side Effects:**
+     * - Creates a new session on the Jules API (`POST /sessions`).
+     * - Initiates background polling for activity updates.
+     * - May create a Pull Request if `autoPr` is true (default).
+     *
+     * **Data Transformation:**
+     * - Resolves the `github` source identifier (e.g., `owner/repo`) to a full resource name.
+     * - Defaults `requirePlanApproval` to `false` for automated runs.
+     *
+     * @param config The configuration for the run.
+     * @returns A `AutomatedSession` object, which is an enhanced Promise that resolves to the final outcome.
+     * @throws {SourceNotFoundError} If the specified GitHub repository cannot be found or accessed.
+     * @throws {JulesApiError} If the session creation fails (e.g., 401 Unauthorized).
+     *
+     * @example
+     * const run = await jules.run({
+     *   prompt: "Fix the login bug",
+     *   source: { github: "my-org/repo", branch: "main" }
+     * });
+     * const outcome = await run.result();
+     */
+    run(config: SessionConfig): Promise<AutomatedSession>;
+    /**
+     * Creates a new interactive session for workflows requiring human oversight.
+     *
+     * **Side Effects:**
+     * - Creates a new session on the Jules API (`POST /sessions`).
+     * - Initializes local storage for the session.
+     *
+     * **Data Transformation:**
+     * - Defaults `requirePlanApproval` to `true` for interactive sessions.
+     *
+     * @param config The configuration for the session.
+     * @returns A Promise resolving to the interactive `SessionClient`.
+     * @throws {SourceNotFoundError} If the source cannot be found.
+     *
+     * @example
+     * const session = await jules.session({
+     *   prompt: "Let's explore the codebase",
+     *   source: { github: "owner/repo", branch: "main" }
+     * });
+     */
+    session(config: SessionConfig): Promise<SessionClient>;
+    /**
+     * Rehydrates an existing session from its ID, allowing you to resume interaction.
+     * This is useful for stateless environments (like serverless functions) where you need to
+     * reconnect to a long-running session.
+     *
+     * **Side Effects:**
+     * - Initializes local storage for the existing session ID.
+     * - Does NOT make a network request immediately (lazy initialization).
+     *
+     * @param sessionId The ID of the existing session.
+     * @returns The interactive `SessionClient`.
+     *
+     * @example
+     * const session = jules.session("12345");
+     * const info = await session.info(); // Now makes a request
+     */
+    session(sessionId: string): SessionClient;
+}

package/dist/errors.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Base class for all SDK-specific errors.
+ * This allows consumers to catch all Jules SDK errors with a single `catch` block.
+ */
+export declare class JulesError extends Error {
+    /** The original error that caused this error, if any. */
+    readonly cause?: Error;
+    constructor(message: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Thrown for fundamental network issues like fetch failures or timeouts.
+ */
+export declare class JulesNetworkError extends JulesError {
+    readonly url: string;
+    constructor(url: string, options?: {
+        cause?: Error;
+    });
+}
+/**
+ * A generic wrapper for non-2xx API responses that don't match other specific errors.
+ */
+export declare class JulesApiError extends JulesError {
+    readonly url: string;
+    readonly status: number;
+    readonly statusText: string;
+    constructor(url: string, status: number, statusText: string, message?: string, // optional override
+    options?: {
+        cause?: Error;
+    });
+}
+/**
+ * Thrown for 401 Unauthorized or 403 Forbidden API responses.
+ */
+export declare class JulesAuthenticationError extends JulesApiError {
+    constructor(url: string, status: number, statusText: string);
+}
+/**
+ * Thrown for 429 Too Many Requests API responses.
+ */
+export declare class JulesRateLimitError extends JulesApiError {
+    constructor(url: string, status: number, statusText: string);
+}
+/**
+ * Thrown when an API key is required but not provided.
+ */
+export declare class MissingApiKeyError extends JulesError {
+    constructor();
+}
+/**
+ * Thrown when a requested source cannot be found.
+ */
+export declare class SourceNotFoundError extends JulesError {
+    constructor(sourceIdentifier: string);
+}
+/**
+ * Thrown when a jules.run() operation terminates in a FAILED state.
+ */
+export declare class AutomatedSessionFailedError extends JulesError {
+    constructor(reason?: string);
+}
+/**
+ * Thrown when an operation is attempted on a session that is not in a
+ * valid state for that operation.
+ */
+export declare class InvalidStateError extends JulesError {
+    constructor(message: string);
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { JulesClient } from './types.js';
+/**
+ * The main entry point for the Jules SDK.
+ * This is a pre-initialized client that can be used immediately with default settings
+ * (e.g., reading API keys from environment variables).
+ *
+ * @example
+ * import { jules } from 'modjules';
+ * const session = await jules.session({ ... });
+ */
+export declare const jules: JulesClient;
+export * from './errors.js';
+export type { Activity, ActivityAgentMessaged, ActivityPlanApproved, ActivityPlanGenerated, ActivityProgressUpdated, ActivitySessionCompleted, ActivitySessionFailed, ActivityUserMessaged, Artifact, AutomatedSession, BashArtifact, ChangeSet, GitHubRepo, GitPatch, JulesClient, JulesOptions, MediaArtifact, Outcome, Plan, PlanStep, PullRequest, SessionClient, SessionConfig, SessionOutput, SessionResource, SessionState, Source, SourceContext, SourceInput, SourceManager, } from './types.js';

package/dist/index.es.js

@@ -0,0 +1,140 @@
+import { J as l } from "./client-D2GRjxRE.mjs";
+import { A as P, I as F, c as z, d as I, a as A, b as O, e as b, M as j, S as $ } from "./client-D2GRjxRE.mjs";
+import * as r from "fs/promises";
+import { createReadStream as c } from "fs";
+import * as s from "path";
+import * as f from "readline";
+import { writeFile as u } from "node:fs/promises";
+import { Buffer as d } from "node:buffer";
+import { setTimeout as h } from "node:timers/promises";
+class m {
+  filePath;
+  initialized = !1;
+  constructor(i, t = process.cwd()) {
+    this.filePath = s.resolve(
+      t,
+      ".jules/cache",
+      i,
+      "activities.jsonl"
+    );
+  }
+  /**
+   * 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.
+   */
+  async init() {
+    this.initialized || (await r.mkdir(s.dirname(this.filePath), { recursive: !0 }), this.initialized = !0);
+  }
+  /**
+   * Closes the storage.
+   */
+  async close() {
+    this.initialized = !1;
+  }
+  /**
+   * 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.
+   */
+  async append(i) {
+    this.initialized || await this.init();
+    const t = JSON.stringify(i) + `
+`;
+    await r.appendFile(this.filePath, t, "utf8");
+  }
+  /**
+   * Retrieves an activity by ID.
+   * Uses a linear scan of the file.
+   */
+  async get(i) {
+    for await (const t of this.scan())
+      if (t.id === i)
+        return t;
+  }
+  /**
+   * Retrieves the latest activity.
+   * Scans the entire file to find the last entry.
+   */
+  async latest() {
+    let i;
+    for await (const t of this.scan())
+      i = t;
+    return i;
+  }
+  /**
+   * 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.
+   */
+  async *scan() {
+    this.initialized || await this.init();
+    try {
+      await r.access(this.filePath);
+    } catch (e) {
+      if (e.code === "ENOENT")
+        return;
+      throw e;
+    }
+    const i = c(this.filePath, { encoding: "utf8" }), t = f.createInterface({
+      input: i,
+      crlfDelay: 1 / 0
+    });
+    for await (const e of t)
+      if (e.trim().length !== 0)
+        try {
+          yield JSON.parse(e);
+        } catch {
+          console.warn(
+            `[NodeFileStorage] Corrupt JSON line ignored in ${this.filePath}`
+          );
+        }
+  }
+}
+class p {
+  /**
+   * Saves a file to the local filesystem using `node:fs/promises`.
+   *
+   * **Side Effects:**
+   * - Writes a file to disk.
+   * - Overwrites the file if it already exists.
+   */
+  async saveFile(i, t, e, o) {
+    const n = d.from(t, e);
+    await u(i, n);
+  }
+  async sleep(i) {
+    await h(i);
+  }
+  createDataUrl(i, t) {
+    return `data:${t};base64,${i}`;
+  }
+}
+const N = new l(
+  {},
+  (a) => new m(a),
+  new p()
+);
+export {
+  P as AutomatedSessionFailedError,
+  F as InvalidStateError,
+  z as JulesApiError,
+  I as JulesAuthenticationError,
+  A as JulesError,
+  O as JulesNetworkError,
+  b as JulesRateLimitError,
+  j as MissingApiKeyError,
+  $ as SourceNotFoundError,
+  N as jules
+};

package/dist/mappers.d.ts

@@ -0,0 +1,34 @@
+import { Activity, Artifact, Outcome, RestArtifact, SessionResource } from './types.js';
+/**
+ * Maps a raw REST API Artifact resource to the SDK's `Artifact` type.
+ * This now instantiates rich classes for certain artifact types.
+ *
+ * @param restArtifact The raw artifact object from the REST API.
+ * @returns A structured `Artifact` object for the SDK.
+ * @internal
+ */
+export declare function mapRestArtifactToSdkArtifact(restArtifact: RestArtifact, platform: any, activityId?: string): Artifact;
+/**
+ * Maps a raw REST API Activity resource to the SDK's discriminated union `Activity` type.
+ *
+ * **Data Transformation:**
+ * - Flattens nested union fields (e.g., `agentMessaged`) into a top-level `type` property.
+ * - Extracts the short ID from the full resource `name`.
+ * - Recursively maps all artifacts within the activity.
+ *
+ * @param restActivity The raw activity object from the REST API.
+ * @param platform The platform adapter (needed for artifact mapping).
+ * @returns A structured `Activity` object for the SDK.
+ * @throws {Error} If the activity type is unknown.
+ * @internal
+ */
+export declare function mapRestActivityToSdkActivity(restActivity: any, platform: any): Activity;
+/**
+ * Maps the final state of a SessionResource to a user-facing Outcome object.
+ * This includes extracting the primary pull request and handling the failed state.
+ *
+ * @param session The final SessionResource from the API.
+ * @returns The corresponding Outcome object.
+ * @throws {AutomatedSessionFailedError} If the session state is 'failed'.
+ */
+export declare function mapSessionResourceToOutcome(session: SessionResource): Outcome;

package/dist/network/adapter.d.ts

@@ -0,0 +1,32 @@
+import { ApiClient } from '../api.js';
+import { NetworkClient } from '../activities/client.js';
+import { Activity } from '../types.js';
+import { ListOptions } from '../activities/types.js';
+import { Platform } from '../platform/types.js';
+/**
+ * Concrete implementation of NetworkClient that communicates with the Jules API.
+ * Handles fetching activities and streaming them via polling.
+ */
+export declare class NetworkAdapter implements NetworkClient {
+    private apiClient;
+    private sessionId;
+    private pollingIntervalMs;
+    private platform;
+    constructor(apiClient: ApiClient, sessionId: string, pollingIntervalMs: number | undefined, platform: Platform);
+    /**
+     * Fetches a single activity from the API.
+     */
+    fetchActivity(activityId: string): Promise<Activity>;
+    /**
+     * Lists activities from the API with pagination.
+     */
+    listActivities(options?: ListOptions): Promise<{
+        activities: Activity[];
+        nextPageToken?: string;
+    }>;
+    /**
+     * Polls the API for new activities and yields them.
+     * This stream never ends unless the process is terminated.
+     */
+    rawStream(): AsyncIterable<Activity>;
+}

package/dist/platform/browser.d.ts

@@ -0,0 +1,25 @@
+import { Platform } from './types.js';
+/**
+ * Browser implementation of the Platform interface.
+ * Uses IndexedDB for file storage.
+ */
+export declare class BrowserPlatform implements Platform {
+    private dbPromise;
+    private getDb;
+    /**
+     * Saves a file to IndexedDB.
+     *
+     * **Data Transformation:**
+     * - Decodes base64 data into a `Blob`.
+     *
+     * **Side Effects:**
+     * - Stores the blob in the `artifacts` object store.
+     * - Associates the file with the `activityId` (if provided).
+     *
+     * @throws {Error} If the encoding is not 'base64'.
+     */
+    saveFile(filepath: string, data: string, encoding: 'base64', activityId?: string): Promise<void>;
+    sleep(ms: number): Promise<void>;
+    createDataUrl(data: string, mimeType: string): string;
+    private base64ToBlob;
+}

package/dist/platform/node.d.ts

@@ -0,0 +1,16 @@
+import { Platform } from './types.js';
+/**
+ * Node.js implementation of the Platform interface.
+ */
+export declare class NodePlatform implements Platform {
+    /**
+     * Saves a file to the local filesystem using `node:fs/promises`.
+     *
+     * **Side Effects:**
+     * - Writes a file to disk.
+     * - Overwrites the file if it already exists.
+     */
+    saveFile(filepath: string, data: string, encoding: 'base64', activityId?: string): Promise<void>;
+    sleep(ms: number): Promise<void>;
+    createDataUrl(data: string, mimeType: string): string;
+}

package/dist/platform/types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Abstract interface for platform-specific functionality.
+ * Allows the SDK to run in both Node.js and browser environments.
+ */
+export interface Platform {
+    /**
+     * Saves a file to the platform's filesystem.
+     */
+    saveFile(filepath: string, data: string, encoding: 'base64', activityId?: string): Promise<void>;
+    /**
+     * Pauses execution for the specified duration.
+     */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Creates a data URL for the given data.
+     */
+    createDataUrl(data: string, mimeType: string): string;
+}

package/dist/polling.d.ts

@@ -0,0 +1,24 @@
+import { ApiClient } from './api.js';
+import { SessionResource } from './types.js';
+/**
+ * A generalized utility for polling the session resource until a specific
+ * condition is met.
+ *
+ * @param sessionId The ID of the session to poll.
+ * @param apiClient The API client for making requests.
+ * @param predicateFn A function that returns `true` if polling should stop.
+ * @param pollingInterval The interval in milliseconds between poll attempts.
+ * @returns The session resource that satisfied the predicate.
+ * @internal
+ */
+export declare function pollSession(sessionId: string, apiClient: ApiClient, predicateFn: (session: SessionResource) => boolean, pollingInterval: number): Promise<SessionResource>;
+/**
+ * Polls the `GET /sessions/{id}` endpoint until the session reaches a terminal state.
+ *
+ * @param sessionId The ID of the session to poll.
+ * @param apiClient The API client for making requests.
+ * @param pollingInterval The interval in milliseconds between poll attempts.
+ * @returns The final SessionResource.
+ * @internal
+ */
+export declare function pollUntilCompletion(sessionId: string, apiClient: ApiClient, pollingInterval: number): Promise<SessionResource>;

package/dist/session.d.ts

@@ -0,0 +1,121 @@
+import { SelectOptions } from './activities/types.js';
+import { ApiClient } from './api.js';
+import { InternalConfig } from './client.js';
+import { ActivityStorage } from './storage/types.js';
+import { StreamActivitiesOptions } from './streaming.js';
+import { Activity, ActivityAgentMessaged, Outcome, SessionClient, SessionResource, SessionState } from './types.js';
+/**
+ * Implementation of the SessionClient interface.
+ * Manages an interactive session with the Jules agent.
+ */
+export declare class SessionClientImpl implements SessionClient {
+    readonly id: string;
+    private apiClient;
+    private config;
+    private _activities;
+    /**
+     * Creates a new instance of SessionClientImpl.
+     *
+     * @param sessionId The ID of the session.
+     * @param apiClient The API client to use for network requests.
+     * @param config The configuration options.
+     * @param storage The storage engine for activities.
+     * @param platform The platform adapter.
+     */
+    constructor(sessionId: string, apiClient: ApiClient, config: InternalConfig, storage: ActivityStorage, platform: any);
+    /**
+     * COLD STREAM: Yields all known past activities from local storage.
+     */
+    history(): AsyncIterable<Activity>;
+    /**
+     * HOT STREAM: Yields ONLY future activities as they arrive from the network.
+     */
+    updates(): AsyncIterable<Activity>;
+    /**
+     * LOCAL QUERY: Performs rich filtering against local storage only.
+     */
+    select(options?: SelectOptions): Promise<Activity[]>;
+    /**
+     * Provides a real-time stream of activities for the session.
+     *
+     * @param options Options to control the stream.
+     */
+    stream(options?: StreamActivitiesOptions): AsyncIterable<Activity>;
+    /**
+     * Approves the currently pending plan.
+     * Only valid if the session state is `awaitingPlanApproval`.
+     *
+     * **Side Effects:**
+     * - Sends a POST request to `sessions/{id}:approvePlan`.
+     * - Transitions the session state from `awaitingPlanApproval` to `inProgress` (eventually).
+     *
+     * @throws {InvalidStateError} If the session is not in the `awaitingPlanApproval` state.
+     *
+     * @example
+     * await session.waitFor('awaitingPlanApproval');
+     * await session.approve();
+     */
+    approve(): Promise<void>;
+    /**
+     * Sends a message (prompt) to the agent in the context of the current session.
+     * This is a fire-and-forget operation. To see the response, use `stream()` or `ask()`.
+     *
+     * **Side Effects:**
+     * - Sends a POST request to `sessions/{id}:sendMessage`.
+     * - Appends a new `userMessaged` activity to the session history.
+     *
+     * @param prompt The message to send.
+     *
+     * @example
+     * await session.send("Please clarify step 2.");
+     */
+    send(prompt: string): Promise<void>;
+    /**
+     * Sends a message to the agent and waits specifically for the agent's immediate reply.
+     * This provides a convenient request/response flow for conversational interactions.
+     *
+     * **Behavior:**
+     * - Sends the prompt using `send()`.
+     * - Subscribes to the activity stream.
+     * - Resolves with the first `agentMessaged` activity that appears *after* the prompt was sent.
+     *
+     * @param prompt The message to send.
+     * @returns The agent's reply activity.
+     * @throws {JulesError} If the session terminates before the agent replies.
+     *
+     * @example
+     * const reply = await session.ask("What is the status?");
+     * console.log(reply.message);
+     */
+    ask(prompt: string): Promise<ActivityAgentMessaged>;
+    /**
+     * Waits for the session to reach a terminal state and returns the result.
+     *
+     * **Behavior:**
+     * - Polls the session API until state is 'completed' or 'failed'.
+     * - Maps the final session resource to a friendly `Outcome` object.
+     *
+     * @returns The final outcome of the session.
+     * @throws {AutomatedSessionFailedError} If the session ends in a 'failed' state.
+     */
+    result(): Promise<Outcome>;
+    /**
+     * Pauses execution and waits until the session reaches a specific state.
+     * Also returns if the session reaches a terminal state ('completed' or 'failed')
+     * to prevent infinite waiting.
+     *
+     * **Behavior:**
+     * - Polls the session API at the configured interval.
+     * - Resolves immediately if the session is already in the target state (or terminal).
+     *
+     * @param targetState The target state to wait for.
+     *
+     * @example
+     * await session.waitFor('awaitingPlanApproval');
+     */
+    waitFor(targetState: SessionState): Promise<void>;
+    /**
+     * Retrieves the latest state of the underlying session resource from the API.
+     */
+    info(): Promise<SessionResource>;
+}

package/dist/sources.d.ts

@@ -0,0 +1,8 @@
+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/storage/browser.d.ts

@@ -0,0 +1,48 @@
+import { Activity } from '../types.js';
+import { ActivityStorage } from './types.js';
+/**
+ * Browser implementation of ActivityStorage using IndexedDB.
+ * Allows for persistent storage of activities in the browser.
+ */
+export declare class BrowserStorage implements ActivityStorage {
+    private sessionId;
+    private dbPromise;
+    constructor(sessionId: string);
+    private getDb;
+    /**
+     * Initializes the storage.
+     *
+     * **Side Effects:**
+     * - Opens an IndexedDB connection.
+     * - Upgrades the database schema to v2 if necessary (creating object stores).
+     */
+    init(): Promise<void>;
+    /**
+     * Closes the storage connection.
+     */
+    close(): Promise<void>;
+    /**
+     * Appends an activity to IndexedDB.
+     *
+     * **Side Effects:**
+     * - Adds a `sessionId` field to the activity for indexing.
+     * - Writes the modified activity to the `activities` object store.
+     */
+    append(activity: Activity): Promise<void>;
+    /**
+     * Retrieves an activity by ID.
+     */
+    get(activityId: string): Promise<Activity | undefined>;
+    /**
+     * Retrieves the latest activity for the current session.
+     *
+     * **Logic:**
+     * - Uses the `sessionTimestamp` index to query efficiently.
+     * - Opens a cursor in 'prev' direction to find the last entry first.
+     */
+    latest(): Promise<Activity | undefined>;
+    /**
+     * Yields all activities for the current session.
+     */
+    scan(): AsyncIterable<Activity>;
+}