modjules 0.1.1

package/README.md

@@ -0,0 +1,319 @@
+# modjules - the agent-ready SDK for Jules
+
+> **Disclaimer:** This is a 100% total, absolute, **just-for-fun** prototype.
+
+## Making Jules Agent-Ready
+
+Agents thrive on simple actions, persistent memory, and reactive updates. `modjules` provides an tool and memory agent toolkit on top of the Jules REST API.
+
+- **Tool Oriented:** Abstracts multi-step API choreographies into single, awaitable tool calls that an agent can easily execute. (e.g., `create session → poll for status → fetch result`)
+- **Persistent State:** Provides external memory, retaining conversational context across turns without burdening your agent's context window.
+- **Reactive Streams:** Converts passive REST polling into push-style Async Iterators, allowing your agent to efficiently _observe_ progress in real-time without managing complex polling logic.
+
+## Core Usage
+
+```ts
+import { jules } from 'modjules';
+
+const session = jules.run({
+  prompt: `Fix visibility issues in the examples/nextjs app. 
+  
+  **Visibility issues**
+  - White text on white backgrounds
+  - Low contrast on button hover
+
+  **Instructions**
+  - Update the global styles and page components to a dark theme with the shadcn zinc palette.
+`,
+  source: { github: 'davideast/modjules', branch: 'main' },
+});
+
+for await (const activity of session.stream()) {
+  switch (activity.type) {
+    case 'progressUpdated':
+      console.log(`[BUSY] ${activity.title}`);
+      break;
+    case 'planGenerated':
+      console.log(`[PLAN] ${activity.plan.steps.length} steps.`);
+      break;
+    case 'sessionCompleted':
+      console.log('[DONE] Session finished successfully.');
+      break;
+    case 'sessionFailed':
+      console.error(`[FAIL] ${activity.reason}`);
+      break;
+  }
+}
+
+// Get the pull-request URL once complete
+const { pullRequest } = await session;
+if (pullRequest) {
+  console.log(`PR: ${pullRequest.url}`);
+}
+```
+
+## Batch Processing
+
+Process multiple items in parallel with `jules.all()`. This method is designed to feel like `Promise.all()` but with built-in concurrency control.
+
+```javascript
+const todos = ['Fix login bug', 'Update README', 'Refactor tests'];
+
+// Processes items concurrently (default: 4 at a time)
+const sessions = await jules.all(todos, (task) => ({
+  prompt: task,
+  source: { github: 'user/repo', branch: 'main' },
+}));
+
+// The results array preserves the order of the input array
+console.log(`Created ${sessions.length} sessions.`);
+```
+
+For more control, you can pass an options object:
+
+```javascript
+const sessions = await jules.all(largeList, mapFn, {
+  concurrency: 10, // Run 10 at a time
+  stopOnError: false, // Don't stop if one fails
+  delayMs: 500, // Wait 500ms between starting each item
+});
+```
+
+### Rich Local Querying
+
+The local cache can be queried instantly without network latency using the `.select()` method.
+
+```typescript
+// Query your local cache instantly without network latency.
+const errors = await session.select({
+  type: 'sessionFailed',
+  limit: 10,
+});
+```
+
+## Installation
+
+```bash
+npm i modjules
+# OR
+bun add modjules
+```
+
+## Cross-Platform Usage
+
+The `modjules` SDK is designed to work seamlessly in both Node.js and browser environments. It uses conditional exports in its `package.json` to automatically provide the correct implementation for your platform.
+
+### Node.js (Default)
+
+In a Node.js environment, the SDK defaults to using the local filesystem for caching session activities in a `.jules/cache` directory. This provides a persistent, restart-safe experience.
+
+```typescript
+// Imports the Node.js version by default
+import { jules } from 'modjules';
+
+const session = await jules.session({
+  prompt: 'Refactor the user authentication module.',
+  source: { github: 'your-org/your-repo', branch: 'develop' },
+});
+```
+
+### Browser
+
+When used in a browser environment (e.g., in a web application bundled with Vite, Webpack, or Rollup), the SDK automatically uses a browser-specific implementation that leverages IndexedDB for storage. This allows your web application to maintain session state locally.
+
+> **Warning:** Never expose your `JULES_API_KEY` in a production or public-facing application. The browser module is designed for trusted client environments like Electron apps or websites running exclusively on a local machine.
+
+To use the browser version, you can explicitly import it:
+
+```typescript
+// Explicitly import the browser-optimized version
+import { jules } from 'modjules/browser';
+
+// The rest of your code remains the same
+const session = await jules.session({
+  prompt: 'Refactor the user authentication module.',
+  source: { github: 'your-org/your-repo', branch: 'develop' },
+});
+```
+
+### Bundler Resolution vs. Explicit Imports
+
+There are two primary strategies for handling platform-specific code, and `modjules` is designed to support both.
+
+1.  **Automatic Resolution (Recommended for most cases):** Modern bundlers that support the `exports` field in `package.json` can automatically select the correct file based on the environment. For example, Vite, when building for the browser, will see the `browser` condition in the `exports` map and use the `dist/browser.es.js` file. This is the ideal scenario, as it requires no changes to your import statements.
+
+    ```typescript
+    // In a browser environment, the bundler will automatically
+    // resolve this to the browser-specific build.
+    import { jules } from 'modjules';
+    ```
+
+2.  **Explicit Imports:** In some cases, you may want to be explicit about which version you are using, or your tooling may not fully support conditional exports. In these situations, you can use a direct import path.
+
+    ```typescript
+    // Always imports the browser version, regardless of bundler configuration
+    import { jules } from 'modjules/browser';
+    ```
+
+**When to choose which?**
+
+- Use the **default import (`modjules`)** whenever possible. It's cleaner and relies on the standard module resolution features of the JavaScript ecosystem.
+- Use the **explicit import (`modjules/browser`)** if you need to override the bundler's resolution, if you are working in an environment that doesn't support conditional exports, or if you want to be very clear in your code that you are using the browser-specific version.
+
+## Authentication / API Key
+
+```bash
+export JULES_API_KEY=<api-key>
+```
+
+## Interactive Usage
+
+Use `jules.session()` for interactive workflows to observe, provide feedback, and guide the process. The `SessionClient` object maintains state across multiple interactions.
+
+```typescript
+import { jules } from 'modjules';
+
+const session = await jules.session({
+  prompt: 'Refactor the user authentication module.',
+  source: { github: 'your-org/your-repo', branch: 'develop' },
+});
+
+console.log(`Session created: ${session.id}`);
+console.log('Waiting for the agent to generate a plan...');
+
+// Wait for the specific state where the plan is ready for review
+await session.waitFor('awaitingPlanApproval');
+console.log('Plan is ready. Approving it now.');
+await session.approve();
+
+// Ask a follow-up question
+const reply = await session.ask(
+  'Start with the first step and let me know when it is done.',
+);
+console.log(`[AGENT] ${reply.message}`);
+
+// Wait for the final result of the session
+const outcome = await session.result();
+console.log(`✅ Session finished with state: ${outcome.state}`);
+```
+
+## Deep Dive
+
+### Reactive Streams
+
+Sessions progress is observed through the `.stream()` method that is available on both the `AutomatedSession` and `SessionClient` objects. An `AutomatedSession` is created via `jules.run()` and a `SessionClient` is create via `jules.session()`. The `.stream()` method returns an `AsyncIterator` to observe the agent's progress.
+
+```typescript
+for await (const activity of session.stream()) {
+  switch (activity.type) {
+    case 'planGenerated':
+      console.log(
+        'Plan:',
+        activity.plan.steps.map((s) => s.title),
+      );
+      break;
+    case 'agentMessaged':
+      console.log('Agent says:', activity.message);
+      break;
+    case 'sessionCompleted':
+      console.log('Session complete!');
+      break;
+  }
+}
+```
+
+### Artifacts (change sets, bash outputs, images)
+
+Session progress is represented through an `Activity` object. Activities can contain artifacts, such as code changes (`changeSet`), shell output (`bashOutput`), or images (`media`). The SDK provides rich objects with helper methods for interacting with them.
+
+```typescript
+// (Inside a stream loop)
+for (const artifact of activity.artifacts) {
+  if (artifact.type === 'bashOutput') {
+    // The .toString() helper formats the command, output, and exit code
+    console.log(artifact.toString());
+  }
+  if (artifact.type === 'media' && artifact.format === 'image/png') {
+    // The .save() helper works in both Node.js and browser environments
+    await artifact.save(`./screenshots/${activity.id}.png`);
+
+    // Get a URL for display or download (works cross-platform)
+    const url = artifact.toUrl();
+    console.log('Screenshot URL:', url);
+  }
+}
+```
+
+### Configuration
+
+You can configure timeouts and polling intervals by creating a configured client.
+
+#### Multiple API Keys
+
+```typescript
+import { jules } from 'modjules';
+
+// The default jules client initialized with process.env.JULES_API_KEY
+const session = jules.session('<session-id-here>');
+
+// Initializes a jules client with another API key
+const customJules = jules.with({ apiKey: 'other-api-key' });
+const session = customJules.session('<session-id-here>');
+```
+
+#### Polling & Timeouts
+
+```typescript
+import { jules } from 'modjules';
+
+const customJules = jules.with({
+  pollingIntervalMs: 2000, // Poll every 2 seconds
+  requestTimeoutMs: 60000, // 1 minute request timeout
+});
+
+// Use the jules client the same as the default
+const session = jules.session('<session-id-here>');
+```
+
+### Error Handling
+
+The SDK throws custom errors that extend a base `JulesError`. This makes it easy to catch all SDK-related exceptions.
+
+```typescript
+import { jules, JulesError } from 'modjules';
+
+try {
+  const session = await jules.session({ ... });
+} catch (error) {
+  if (error instanceof JulesError) {
+    console.error(`An SDK error occurred: ${error.message}`);
+  } else {
+    console.error(`An unexpected error occurred: ${error}`);
+  }
+}
+```
+
+## API Overview
+
+This is a high-level overview of the main SDK components.
+
+- **Core:**
+  - `jules`: The pre-initialized client.
+  - `jules.with(options)`: Creates a new client with custom configuration.
+  - `jules.session()`: Creates or rehydrates a session. Returns a `SessionClient`.
+- **Session Control:**
+  - `session.ask()`: Sends a message and awaits the agent's reply.
+  - `session.send()`: Sends a fire-and-forget message.
+  - `session.approve()`: Approves a pending plan.
+  - `session.waitFor()`: Pauses until the session reaches a specific state.
+  - `session.waitForCompletion()`: Awaits the final outcome of the session.
+- **Observation:**
+  - `session.stream()`: Returns an async iterator of all activities (history + live).
+  - `session.history()`: Returns a stream of locally cached activities.
+  - `session.updates()`: Returns a stream of live activities from the network.
+  - `session.select(query)`: Queries the local activity cache.
+  - `session.info()`: Fetches the latest session state.
+- **Artifact Management:**
+  - `artifact.save()`: Decodes the base64 `data` and saves it. In Node.js, it writes to the filesystem. In the browser, it saves to IndexedDB.
+  - `artifact.toUrl()`: Returns a `data:` URI for the artifact data, usable in both Node.js and browser.
+  - `artifact.toString()`: Returns a formatted string that combines the command, exit code, `stdout`, and `stderr`, to simplify log display.

package/dist/activities/client.d.ts

@@ -0,0 +1,79 @@
+import { Activity } from '../types.js';
+import { ActivityStorage } from '../storage/types.js';
+import { ActivityClient, ListOptions, SelectOptions } from './types.js';
+/**
+ * Interface for the network layer used by the activity client.
+ * Abstracts away the details of polling and fetching from the API.
+ * @internal
+ */
+export interface NetworkClient {
+    rawStream(): AsyncIterable<Activity>;
+    listActivities(options?: ListOptions): Promise<{
+        activities: Activity[];
+        nextPageToken?: string;
+    }>;
+    fetchActivity(activityId: string): Promise<Activity>;
+}
+/**
+ * The default implementation of the ActivityClient.
+ * Implements a "local-first" architecture where activities are fetched from
+ * the network, cached locally, and then served from the cache.
+ */
+export declare class DefaultActivityClient implements ActivityClient {
+    private storage;
+    private network;
+    constructor(storage: ActivityStorage, network: NetworkClient);
+    /**
+     * Returns an async iterable of all activities stored locally.
+     */
+    history(): AsyncIterable<Activity>;
+    /**
+     * Returns an async iterable of new activities from the network.
+     * This method polls the network and updates the local storage.
+     *
+     * **Side Effects:**
+     * - Polls the network continuously.
+     * - Appends new activities to local storage (write-through caching).
+     *
+     * **Logic:**
+     * - Reads the latest activity from storage to determine the "high-water mark".
+     * - Ignores incoming activities older than or equal to the high-water mark.
+     */
+    updates(): AsyncIterable<Activity>;
+    /**
+     * Returns a combined stream of history and updates.
+     * This is the primary method for consuming the activity stream.
+     *
+     * **Behavior:**
+     * 1. Yields all historical activities from local storage (offline capable).
+     * 2. Switches to `updates()` to yield new activities from the network (real-time).
+     */
+    stream(): AsyncIterable<Activity>;
+    /**
+     * Queries local storage for activities matching the given options.
+     */
+    select(options?: SelectOptions): Promise<Activity[]>;
+    /**
+     * Lists activities from the network directly.
+     * @param options Pagination options.
+     */
+    list(options?: ListOptions): Promise<{
+        activities: Activity[];
+        nextPageToken?: string;
+    }>;
+    /**
+     * Gets a single activity by ID.
+     * Implements a "read-through" caching strategy.
+     *
+     * **Logic:**
+     * 1. Checks local storage. If found, returns it immediately (fast).
+     * 2. If missing, fetches from the network.
+     * 3. Persists the fetched activity to storage (future reads will hit cache).
+     * 4. Returns the activity.
+     *
+     * **Side Effects:**
+     * - May perform a network request.
+     * - May write to local storage.
+     */
+    get(activityId: string): Promise<Activity>;
+}

package/dist/activities/types.d.ts

@@ -0,0 +1,56 @@
+import { Activity } from '../types.js';
+/**
+ * Standard pagination options for network requests.
+ */
+export interface ListOptions {
+    pageSize?: number;
+    pageToken?: string;
+}
+/**
+ * Options for filtering activities locally.
+ */
+export interface SelectOptions {
+    after?: string;
+    before?: string;
+    type?: string;
+    limit?: number;
+}
+/**
+ * Interface for managing session activities.
+ * This interface handles both local caching and network synchronization.
+ */
+export interface ActivityClient {
+    /**
+     * COLD STREAM: Yields all known past activities from local storage.
+     * Ends immediately after yielding the last known activity.
+     * Does NOT open a network connection.
+     */
+    history(): AsyncIterable<Activity>;
+    /**
+     * HOT STREAM: Yields ONLY future activities as they arrive from the network.
+     * Blocks indefinitely.
+     */
+    updates(): AsyncIterable<Activity>;
+    /**
+     * HYBRID STREAM: Yields full history(), then seamlessly switches to updates().
+     * The standard choice for most applications.
+     */
+    stream(): AsyncIterable<Activity>;
+    /**
+     * LOCAL QUERY: Performs rich filtering against local storage only.
+     * Fast, but might be incomplete if not synced.
+     */
+    select(options?: SelectOptions): Promise<Activity[]>;
+    /**
+     * NETWORK LIST: Honest wrapper around standard REST pagination.
+     * Uses opaque tokens.
+     */
+    list(options?: ListOptions): Promise<{
+        activities: Activity[];
+        nextPageToken?: string;
+    }>;
+    /**
+     * NETWORK GET: Fetches a specific activity from the network and caches it.
+     */
+    get(activityId: string): Promise<Activity>;
+}

package/dist/api.d.ts

@@ -0,0 +1,21 @@
+export type ApiClientOptions = {
+    apiKey: string | undefined;
+    baseUrl: string;
+    requestTimeoutMs: number;
+};
+export type ApiRequestOptions = {
+    method?: 'GET' | 'POST';
+    body?: Record<string, unknown>;
+    params?: Record<string, string>;
+};
+/**
+ * A simple internal API client to handle HTTP requests to the Jules API.
+ * @internal
+ */
+export declare class ApiClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly requestTimeoutMs;
+    constructor(options: ApiClientOptions);
+    request<T>(endpoint: string, options?: ApiRequestOptions): Promise<T>;
+}

package/dist/artifacts.d.ts

@@ -0,0 +1,54 @@
+import { RestMediaArtifact, RestBashOutputArtifact } from './types.js';
+import { Platform } from './platform/types.js';
+/**
+ * Represents a media artifact (e.g. image) produced by an activity.
+ * Provides helper methods for saving and viewing the media.
+ */
+export declare class MediaArtifact {
+    readonly type = "media";
+    readonly data: string;
+    readonly format: string;
+    private platform;
+    private activityId?;
+    constructor(artifact: RestMediaArtifact['media'], platform: Platform, activityId?: string);
+    /**
+     * Saves the media artifact to a file.
+     *
+     * **Side Effects:**
+     * - Node.js: Writes the file to disk (overwrites if exists).
+     * - Browser: Saves the file to the 'artifacts' object store in IndexedDB.
+     *
+     * @param filepath The path where the file should be saved.
+     */
+    save(filepath: string): Promise<void>;
+    /**
+     * Converts the media artifact to a data URL.
+     * Useful for displaying images in a browser.
+     *
+     * **Data Transformation:**
+     * - Prefixes the base64 data with `data:<mimeType>;base64,`.
+     *
+     * @returns A valid Data URI string.
+     */
+    toUrl(): string;
+}
+/**
+ * Represents the output of a bash command executed by the agent.
+ */
+export declare class BashArtifact {
+    readonly type = "bashOutput";
+    readonly command: string;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number | null;
+    constructor(artifact: RestBashOutputArtifact['bashOutput']);
+    /**
+     * Formats the bash output as a string, mimicking a terminal session.
+     *
+     * **Data Transformation:**
+     * - Combines `stdout` and `stderr`.
+     * - Formats the command with a `$` prompt.
+     * - Appends the exit code.
+     */
+    toString(): string;
+}

package/dist/browser.d.ts

@@ -0,0 +1,12 @@
+import { JulesClient } from './types.js';
+/**
+ * The main entry point for the Jules SDK for browser environments.
+ * This is a pre-initialized client that can be used immediately with default settings.
+ *
+ * @example
+ * import { jules } from 'modjules/browser';
+ * 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';