modjules 0.1.1 → 0.2.0

package/dist/query/computed.d.ts

@@ -0,0 +1,65 @@
+import { Activity } from '../types.js';
+/**
+ * List of computed field names for activities
+ */
+export declare const ACTIVITY_COMPUTED_FIELDS: readonly ["artifactCount", "summary"];
+/**
+ * List of computed field names for sessions
+ */
+export declare const SESSION_COMPUTED_FIELDS: readonly ["durationMs"];
+/**
+ * Check if a field name is a computed field for activities
+ */
+export declare function isActivityComputedField(field: string): boolean;
+/**
+ * Check if a field name is a computed field for sessions
+ */
+export declare function isSessionComputedField(field: string): boolean;
+/**
+ * Compute the artifactCount for an activity
+ */
+export declare function computeArtifactCount(activity: Activity): number;
+/**
+ * Compute the summary for an activity
+ * Delegates to existing toSummary implementation
+ */
+export declare function computeSummary(activity: Activity): string;
+/**
+ * Compute the duration in milliseconds for a session
+ */
+export declare function computeDurationMs(session: {
+    createTime?: string;
+    updateTime?: string;
+}): number;
+/**
+ * Inject computed fields into an activity based on selected fields
+ *
+ * @param activity The activity to augment
+ * @param selectFields The fields being selected (or undefined for default)
+ * @returns Activity with computed fields added
+ */
+export declare function injectActivityComputedFields(activity: Activity, selectFields?: string[]): Activity & {
+    artifactCount?: number;
+    summary?: string;
+};
+/**
+ * Inject computed fields into a session based on selected fields
+ *
+ * @param session The session to augment
+ * @param selectFields The fields being selected (or undefined for default)
+ * @returns Session with computed fields added
+ */
+export declare function injectSessionComputedFields<T extends {
+    createTime?: string;
+    updateTime?: string;
+}>(session: T, selectFields?: string[]): T & {
+    durationMs?: number;
+};
+/**
+ * Default projection fields for activities (includes computed fields)
+ */
+export declare const DEFAULT_ACTIVITY_PROJECTION: string[];
+/**
+ * Default projection fields for sessions
+ */
+export declare const DEFAULT_SESSION_PROJECTION: string[];

package/dist/query/projection.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Projection Engine for Jules Query Language
+ *
+ * Supports:
+ * - Dot notation field paths: "plan.steps.title"
+ * - Wildcard inclusion: "*"
+ * - Exclusion prefix: "-artifacts.data"
+ * - Implicit array traversal: "artifacts.type" works on arrays
+ */
+/**
+ * Parsed select expression
+ */
+export interface SelectExpression {
+    path: string[];
+    exclude: boolean;
+    wildcard: boolean;
+}
+/**
+ * Parse a select expression string into structured form
+ *
+ * Examples:
+ * - "id" → { path: ["id"], exclude: false, wildcard: false }
+ * - "plan.steps.title" → { path: ["plan", "steps", "title"], exclude: false, wildcard: false }
+ * - "-artifacts.data" → { path: ["artifacts", "data"], exclude: true, wildcard: false }
+ * - "*" → { path: [], exclude: false, wildcard: true }
+ */
+export declare function parseSelectExpression(expr: string): SelectExpression;
+/**
+ * Get a value at a nested path, handling arrays transparently
+ *
+ * For paths that traverse arrays, returns an array of values from each element.
+ *
+ * Examples:
+ * - getPath({a: {b: 1}}, ["a", "b"]) → 1
+ * - getPath({items: [{x: 1}, {x: 2}]}, ["items", "x"]) → [1, 2]
+ */
+export declare function getPath(obj: unknown, path: string[]): unknown;
+/**
+ * Set a value at a nested path, creating intermediate objects as needed
+ *
+ * For array paths, preserves array structure.
+ */
+export declare function setPath(obj: Record<string, unknown>, path: string[], value: unknown): void;
+/**
+ * Delete a value at a nested path
+ *
+ * For paths ending in array elements, removes the field from each element.
+ */
+export declare function deletePath(obj: unknown, path: string[]): void;
+/**
+ * Deep clone an object
+ */
+export declare function deepClone<T>(obj: T): T;
+/**
+ * Project a document according to select expressions
+ *
+ * @param doc The source document
+ * @param selects Array of select expression strings
+ * @returns Projected document with only selected fields
+ */
+export declare function projectDocument(doc: Record<string, unknown>, selects: string[]): Record<string, unknown>;
+/**
+ * Check if a path is a prefix of another path
+ */
+export declare function isPathPrefix(prefix: string[], path: string[]): boolean;

package/dist/query/schema.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Schema Introspection for Jules Query Language
+ *
+ * Provides TypeScript type definitions and field metadata for LLM discoverability.
+ * These schemas help LLMs understand the shape of Session, Activity, and related types
+ * to translate natural language queries into proper JQL.
+ */
+/**
+ * Field metadata for schema introspection
+ */
+export interface FieldMeta {
+    /** Field name */
+    name: string;
+    /** TypeScript type representation */
+    type: string;
+    /** Human-readable description */
+    description: string;
+    /** Whether field is optional */
+    optional?: boolean;
+    /** Whether field is computed (not stored, derived at query time) */
+    computed?: boolean;
+    /** Whether field can be filtered in where clause */
+    filterable?: boolean;
+    /** Whether field can be used in select projection */
+    selectable?: boolean;
+    /** Nested fields if this is an object or array type */
+    fields?: FieldMeta[];
+}
+/**
+ * Schema definition for a domain
+ */
+export interface DomainSchema {
+    /** Domain name */
+    domain: 'sessions' | 'activities';
+    /** Human-readable description */
+    description: string;
+    /** All fields in this domain */
+    fields: FieldMeta[];
+    /** Example queries for this domain */
+    examples: QueryExample[];
+}
+/**
+ * Example query for documentation
+ */
+export interface QueryExample {
+    /** Natural language description */
+    description: string;
+    /** JQL query */
+    query: Record<string, unknown>;
+}
+/**
+ * Schema for SessionResource
+ */
+export declare const SESSION_SCHEMA: DomainSchema;
+/**
+ * Schema for Activity types
+ */
+export declare const ACTIVITY_SCHEMA: DomainSchema;
+/**
+ * FilterOp schema for where clause operators
+ */
+export declare const FILTER_OP_SCHEMA: {
+    description: string;
+    operators: {
+        name: string;
+        description: string;
+        example: string;
+    }[];
+    dotNotation: {
+        description: string;
+        examples: string[];
+    };
+};
+/**
+ * Projection schema for select clause
+ */
+export declare const PROJECTION_SCHEMA: {
+    description: string;
+    syntax: {
+        name: string;
+        description: string;
+        example: string;
+    }[];
+    defaults: {
+        sessions: string[];
+        activities: string[];
+    };
+};
+/**
+ * Get the full schema for a domain
+ */
+export declare function getSchema(domain: 'sessions' | 'activities'): DomainSchema;
+/**
+ * Get all schemas with filter and projection documentation
+ */
+export declare function getAllSchemas(): {
+    sessions: DomainSchema;
+    activities: DomainSchema;
+    filterOps: typeof FILTER_OP_SCHEMA;
+    projection: typeof PROJECTION_SCHEMA;
+};
+/**
+ * Generate TypeScript type definition string for a domain
+ */
+export declare function generateTypeDefinition(domain: 'sessions' | 'activities'): string;
+/**
+ * Generate markdown documentation for LLM consumption
+ */
+export declare function generateMarkdownDocs(): string;

package/dist/query/select.d.ts

@@ -0,0 +1,6 @@
+import { JulesClient, JulesQuery, JulesDomain, QueryResult } from '../types.js';
+/**
+ * Standalone query engine function.
+ * Handles planning, index scanning, and hydration.
+ */
+export declare function select<T extends JulesDomain>(client: JulesClient, query: JulesQuery<T>): Promise<QueryResult<T>[]>;

package/dist/query/validate.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Query Validator for Jules Query Language
+ *
+ * Validates queries before execution, providing actionable error messages
+ * for LLMs to self-correct their queries.
+ */
+export interface ValidationError {
+    /** Error code for programmatic handling */
+    code: ValidationErrorCode;
+    /** JSON path to the error location (e.g., "where.artifacts.type") */
+    path: string;
+    /** Human-readable error message */
+    message: string;
+    /** Suggested fix or valid alternatives */
+    suggestion?: string;
+}
+export interface ValidationWarning {
+    /** Warning code */
+    code: string;
+    /** JSON path to the warning location */
+    path: string;
+    /** Human-readable warning message */
+    message: string;
+}
+export interface ValidationResult {
+    /** Whether the query is valid */
+    valid: boolean;
+    /** Validation errors (if any) */
+    errors: ValidationError[];
+    /** Validation warnings (non-blocking issues) */
+    warnings: ValidationWarning[];
+    /** Auto-corrected query (if corrections were possible) */
+    correctedQuery?: Record<string, unknown>;
+}
+export type ValidationErrorCode = 'INVALID_STRUCTURE' | 'MISSING_REQUIRED_FIELD' | 'INVALID_DOMAIN' | 'INVALID_FIELD_PATH' | 'INVALID_OPERATOR' | 'INVALID_OPERATOR_VALUE' | 'COMPUTED_FIELD_FILTER' | 'INVALID_ORDER' | 'INVALID_LIMIT' | 'INVALID_SELECT_EXPRESSION';
+/**
+ * Validate a Jules Query Language query
+ *
+ * @param query - The query object to validate
+ * @returns Validation result with errors, warnings, and optional corrections
+ *
+ * @example
+ * ```typescript
+ * const result = validateQuery({
+ *   from: 'activities',
+ *   where: { type: 'agentMessaged' },
+ *   select: ['id', 'message']
+ * });
+ *
+ * if (!result.valid) {
+ *   console.log('Errors:', result.errors);
+ * }
+ * ```
+ */
+export declare function validateQuery(query: unknown): ValidationResult;
+/**
+ * Format validation result as a human-readable string
+ */
+export declare function formatValidationResult(result: ValidationResult): string;

package/dist/session.d.ts

@@ -1,9 +1,9 @@
-import { SelectOptions } from './activities/types.js';
+import { ActivityClient, SelectOptions } from './activities/types.js';
 import { ApiClient } from './api.js';
 import { InternalConfig } from './client.js';
-import { ActivityStorage } from './storage/types.js';
+import { ActivityStorage, SessionStorage } from './storage/types.js';
 import { StreamActivitiesOptions } from './streaming.js';
-import { Activity, ActivityAgentMessaged, Outcome, SessionClient, SessionResource, SessionState } from './types.js';
+import { Activity, ActivityAgentMessaged, Outcome, SessionClient, SessionResource, SessionState, SessionSnapshot } from './types.js';
 /**
  * Implementation of the SessionClient interface.
  * Manages an interactive session with the Jules agent.
@@ -12,6 +12,7 @@ export declare class SessionClientImpl implements SessionClient {
     readonly id: string;
     private apiClient;
     private config;
+    private sessionStorage;
     private _activities;
     /**
      * Creates a new instance of SessionClientImpl.
@@ -19,22 +20,37 @@ export declare class SessionClientImpl implements SessionClient {
      * @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 activityStorage The storage engine for activities.
+     * @param sessionStorage The storage engine for sessions.
      * @param platform The platform adapter.
      */
-    constructor(sessionId: string, apiClient: ApiClient, config: InternalConfig, storage: ActivityStorage, platform: any);
+    constructor(sessionId: string, apiClient: ApiClient, config: InternalConfig, activityStorage: ActivityStorage, sessionStorage: SessionStorage, // Injected dependency
+    platform: any);
+    private request;
     /**
      * COLD STREAM: Yields all known past activities from local storage.
+     * If local cache is empty, fetches from network first.
      */
     history(): AsyncIterable<Activity>;
+    /**
+     * Forces a full sync of activities from the network to local cache.
+     * @returns The number of new activities synced.
+     */
+    hydrate(): Promise<number>;
     /**
      * HOT STREAM: Yields ONLY future activities as they arrive from the network.
      */
     updates(): AsyncIterable<Activity>;
     /**
      * LOCAL QUERY: Performs rich filtering against local storage only.
+     *
+     * @deprecated Use `session.activities.select()` instead.
      */
     select(options?: SelectOptions): Promise<Activity[]>;
+    /**
+     * Scoped access to activity-specific operations.
+     */
+    get activities(): ActivityClient;
     /**
      * Provides a real-time stream of activities for the session.
      *
@@ -115,7 +131,15 @@ export declare class SessionClientImpl implements SessionClient {
      */
     waitFor(targetState: SessionState): Promise<void>;
     /**
-     * Retrieves the latest state of the underlying session resource from the API.
+     * Retrieves the latest state of the underlying session resource.
+     * Implements "Iceberg" Read-Through caching.
      */
     info(): Promise<SessionResource>;
+    /**
+     * Creates a point-in-time snapshot of the session.
+     * This is a network operation that fetches the latest session info and all activities.
+     *
+     * @returns A `SessionSnapshot` instance.
+     */
+    snapshot(): Promise<SessionSnapshot>;
 }

package/dist/sessions.d.ts

@@ -0,0 +1,65 @@
+import { ApiClient } from './api.js';
+import { SessionResource } from './types.js';
+import { SessionStorage } from './storage/types.js';
+export type ListSessionsOptions = {
+    pageSize?: number;
+    pageToken?: string;
+    /**
+     * Hard limit on the number of items to yield when iterating.
+     * Useful if you want "The last 50" without manual counting.
+     */
+    limit?: number;
+    /**
+     * Whether to persist fetched sessions to local storage.
+     * Defaults to `true` (Write-Through Caching).
+     * Set to `false` to disable side effects.
+     */
+    persist?: boolean;
+};
+export type ListSessionsResponse = {
+    sessions: SessionResource[];
+    nextPageToken?: string;
+};
+/**
+ * The SessionCursor handles the complexity of pagination state.
+ * It is "Thenable" (acts like a Promise) and "AsyncIterable".
+ *
+ * This allows two usage patterns:
+ * 1. `await jules.sessions()` - Get the first page (Promise behavior).
+ * 2. `for await (const session of jules.sessions())` - Stream all sessions (AsyncIterable behavior).
+ *
+ * **Design Notes:**
+ * - **Pagination:** Handles `nextPageToken` automatically during iteration. For manual control,
+ *   access the `nextPageToken` property on the promised response.
+ * - **Limiting:** The `limit` option hard-stops the iteration after N items, preventing over-fetching.
+ * - **Write-Through Caching:** Fetched sessions are automatically persisted to local storage
+ *   using `storage.upsertMany()`. This ensures the local graph is populated during listing.
+ * - **Platform:** Fully platform-agnostic (Node.js/Browser/GAS) via the injected `ApiClient`.
+ */
+export declare class SessionCursor implements PromiseLike<ListSessionsResponse>, AsyncIterable<SessionResource> {
+    private apiClient;
+    private storage;
+    private options;
+    constructor(apiClient: ApiClient, storage: SessionStorage, options?: ListSessionsOptions);
+    /**
+     * DX Feature: Promise Compatibility.
+     * Allows `const page = await jules.sessions()` to just get the first page.
+     * This is great for UIs that render a list and a "Load More" button.
+     */
+    then<TResult1 = ListSessionsResponse, TResult2 = never>(onfulfilled?: ((value: ListSessionsResponse) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * DX Feature: Async Iterator.
+     * Allows `for await (const s of jules.sessions())` to stream ALL items.
+     * Automatically handles page tokens and fetching behind the scenes.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<SessionResource>;
+    /**
+     * Helper to fetch all pages into a single array.
+     * WARNING: Use with caution on large datasets.
+     */
+    all(): Promise<SessionResource[]>;
+    /**
+     * Internal fetcher that maps the options to the REST parameters.
+     */
+    private fetchPage;
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,23 @@
+import { Activity, PullRequest, SessionInsights, SessionResource, SessionSnapshot, SessionState, SerializedSnapshot, TimelineEntry } from './types.js';
+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;
+    constructor(session: SessionResource, activities: Activity[]);
+    private computeActivityCounts;
+    private computeTimeline;
+    private generateSummary;
+    private computeInsights;
+    toJSON(): SerializedSnapshot;
+    toMarkdown(): string;
+}

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

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

@@ -1,5 +1,5 @@
-import { Activity } from '../types.js';
-import { ActivityStorage } from './types.js';
+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.
@@ -38,3 +38,16 @@ export declare class MemoryStorage implements ActivityStorage {
      */
     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/storage/node-fs.d.ts

@@ -1,13 +1,14 @@
-import { Activity } from '../types.js';
-import { ActivityStorage } from './types.js';
+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;
-    constructor(sessionId: string, rootDir?: string);
+    constructor(sessionId: string, rootDir: string);
     /**
      * Initializes the storage by ensuring the cache directory exists.
      *
@@ -20,6 +21,8 @@ export declare class NodeFileStorage implements ActivityStorage {
      * Closes the storage.
      */
     close(): Promise<void>;
+    private _readMetadata;
+    private _writeMetadata;
     /**
      * Appends an activity to the file.
      *
@@ -52,3 +55,16 @@ export declare class NodeFileStorage implements ActivityStorage {
      */
     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/storage/root.d.ts

@@ -0,0 +1,2 @@
+export declare function isWritable(dir: string): boolean;
+export declare function getRootDir(): string;

package/dist/storage/types.d.ts

@@ -1,4 +1,62 @@
-import { Activity } from '../types.js';
+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
@@ -36,3 +94,7 @@ export interface ActivityStorage {
      */
     scan(): AsyncIterable<Activity>;
 }
+export interface GlobalCacheMetadata {
+    lastSyncedAt: number;
+    sessionCount: number;
+}