@google/jules-merge 0.0.1

package/dist/core/src/query/computed.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+/**
+ * Computed Fields for Jules Query Language
+ *
+ * Computed fields are derived at query time, not stored.
+ * They can be selected but not filtered.
+ */
+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/core/src/query/projection.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+/**
+ * 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/core/src/query/schema.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ */
+/**
+ * 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/core/src/query/select.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 { 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/core/src/query/validate.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 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/core/src/session.d.ts

@@ -0,0 +1,195 @@
+/**
+ * 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 { ActivityClient, SelectOptions } from './activities/types.js';
+import { ApiClient } from './api.js';
+import { InternalConfig } from './client.js';
+import { ActivityStorage, SessionStorage } from './storage/types.js';
+import { StreamActivitiesOptions } from './streaming.js';
+import { Activity, ActivityAgentMessaged, SessionOutcome, SessionClient, SessionResource, SessionState } from './types.js';
+import { SessionSnapshot } 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 sessionStorage;
+    private _activities;
+    private platform;
+    /**
+     * 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 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, 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.
+     *
+     * @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.
+     *
+     * @param options Optional configuration for the operation.
+     * @param options.timeoutMs Maximum time in milliseconds to wait for the session to complete.
+     * @returns The final outcome of the session.
+     * @throws {AutomatedSessionFailedError} If the session ends in a 'failed' state.
+     * @throws {TimeoutError} If the operation times out.
+     */
+    result(options?: {
+        timeoutMs?: number;
+    }): Promise<SessionOutcome>;
+    /**
+     * 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.
+     * @param options Optional configuration for the operation.
+     * @param options.timeoutMs Maximum time in milliseconds to wait for the state.
+     * @throws {TimeoutError} If the operation times out.
+     *
+     * @example
+     * await session.waitFor('awaitingPlanApproval');
+     */
+    waitFor(targetState: SessionState, options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Archives the session.
+     * This removes the session from the default list view and marks it as archived.
+     * Archived sessions can still be accessed by ID or by filtering for `archived = true`.
+     *
+     * **Side Effects:**
+     * - Sends a POST request to `sessions/{id}:archive`.
+     * - Updates the local cache to mark the session as archived.
+     */
+    archive(): Promise<void>;
+    /**
+     * Unarchives the session.
+     * This restores the session to the default list view.
+     *
+     * **Side Effects:**
+     * - Sends a POST request to `sessions/{id}:unarchive`.
+     * - Updates the local cache to mark the session as not archived.
+     */
+    unarchive(): Promise<void>;
+    /**
+     * 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.
+     *
+     * @param options Optional configuration for the snapshot.
+     * @param options.activities If true, includes all activities in the snapshot. Defaults to true.
+     * @returns A `SessionSnapshot` instance.
+     */
+    snapshot(options?: {
+        activities?: boolean;
+    }): Promise<SessionSnapshot>;
+}

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

@@ -0,0 +1,87 @@
+/**
+ * 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 { 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;
+    /**
+     * Filter expression to restrict the sessions returned.
+     * The syntax follows the AIP-160 standard (e.g., `archived = true`).
+     * By default, archived sessions are excluded.
+     */
+    filter?: string;
+};
+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 platform;
+    private options;
+    constructor(apiClient: ApiClient, storage: SessionStorage, platform: any, 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;
+}