@google/jules-merge 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +201 -0
- package/dist/cli/check-conflicts.command.mjs +387 -0
- package/dist/cli/index.mjs +28 -0
- package/dist/cli/init.command.mjs +159 -0
- package/dist/core/src/activities/client.d.ts +131 -0
- package/dist/core/src/activities/summary.d.ts +22 -0
- package/dist/core/src/activities/types.d.ts +79 -0
- package/dist/core/src/api.d.ts +49 -0
- package/dist/core/src/artifacts.d.ts +105 -0
- package/dist/core/src/caching.d.ts +31 -0
- package/dist/core/src/client.d.ts +180 -0
- package/dist/core/src/errors.d.ts +97 -0
- package/dist/core/src/index.d.ts +49 -0
- package/dist/core/src/mappers.d.ts +53 -0
- package/dist/core/src/network/adapter.d.ts +47 -0
- package/dist/core/src/platform/node.d.ts +45 -0
- package/dist/core/src/platform/types.d.ts +88 -0
- package/dist/core/src/polling.d.ts +43 -0
- package/dist/core/src/query/computed.d.ts +86 -0
- package/dist/core/src/query/projection.d.ts +80 -0
- package/dist/core/src/query/schema.d.ts +124 -0
- package/dist/core/src/query/select.d.ts +21 -0
- package/dist/core/src/query/validate.d.ts +68 -0
- package/dist/core/src/session.d.ts +195 -0
- package/dist/core/src/sessions.d.ts +87 -0
- package/dist/core/src/snapshot.d.ts +46 -0
- package/dist/core/src/sources.d.ts +23 -0
- package/dist/core/src/storage/cache-info.d.ts +43 -0
- package/dist/core/src/storage/memory.d.ts +69 -0
- package/dist/core/src/storage/node-fs.d.ts +95 -0
- package/dist/core/src/storage/root.d.ts +17 -0
- package/dist/core/src/storage/types.d.ts +115 -0
- package/dist/core/src/streaming.d.ts +47 -0
- package/dist/core/src/types.d.ts +1418 -0
- package/dist/core/src/utils/page-token.d.ts +55 -0
- package/dist/core/src/utils.d.ts +27 -0
- package/dist/index.mjs +395 -0
- package/dist/merge/src/__tests__/conflicts/git-handler.test.d.ts +1 -0
- package/dist/merge/src/__tests__/conflicts/git-spec.test.d.ts +1 -0
- package/dist/merge/src/__tests__/conflicts/session-handler.test.d.ts +1 -0
- package/dist/merge/src/__tests__/conflicts/session-spec.test.d.ts +1 -0
- package/dist/merge/src/__tests__/init/init-handler.test.d.ts +1 -0
- package/dist/merge/src/__tests__/init/init-spec.test.d.ts +1 -0
- package/dist/merge/src/__tests__/init/templates.test.d.ts +1 -0
- package/dist/merge/src/__tests__/shared/git.test.d.ts +1 -0
- package/dist/merge/src/__tests__/shared/github.test.d.ts +1 -0
- package/dist/merge/src/__tests__/shared/session.test.d.ts +1 -0
- package/dist/merge/src/cli/check-conflicts.command.d.ts +24 -0
- package/dist/merge/src/cli/index.d.ts +2 -0
- package/dist/merge/src/cli/init.command.d.ts +23 -0
- package/dist/merge/src/conflicts/git-handler.d.ts +4 -0
- package/dist/merge/src/conflicts/git-spec.d.ts +43 -0
- package/dist/merge/src/conflicts/index.d.ts +4 -0
- package/dist/merge/src/conflicts/session-handler.d.ts +9 -0
- package/dist/merge/src/conflicts/session-spec.d.ts +43 -0
- package/dist/merge/src/index.d.ts +5 -0
- package/dist/merge/src/init/index.d.ts +4 -0
- package/dist/merge/src/init/init-handler.d.ts +4 -0
- package/dist/merge/src/init/init-spec.d.ts +41 -0
- package/dist/merge/src/init/templates.d.ts +10 -0
- package/dist/merge/src/mcp/index.d.ts +1 -0
- package/dist/merge/src/mcp/server.d.ts +2 -0
- package/dist/merge/src/shared/git.d.ts +17 -0
- package/dist/merge/src/shared/github.d.ts +18 -0
- package/dist/merge/src/shared/result.d.ts +19 -0
- package/dist/merge/src/shared/session.d.ts +16 -0
- package/package.json +60 -0
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Copyright 2026 Google LLC
|
|
3
|
+
*
|
|
4
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
* you may not use this file except in compliance with the License.
|
|
6
|
+
* You may obtain a copy of the License at
|
|
7
|
+
*
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
*
|
|
10
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
* See the License for the specific language governing permissions and
|
|
14
|
+
* limitations under the License.
|
|
15
|
+
*/
|
|
16
|
+
import { JulesClient, JulesOptions, SessionConfig, SourceManager, AutomatedSession, SessionClient, SessionResource, StorageFactory } from './types.js';
|
|
17
|
+
import { SessionCursor, ListSessionsOptions } from './sessions.js';
|
|
18
|
+
import { Platform } from './platform/types.js';
|
|
19
|
+
import { SessionStorage } from './storage/types.js';
|
|
20
|
+
import { JulesQuery, JulesDomain, QueryResult, SyncOptions, SyncStats } from './types.js';
|
|
21
|
+
/**
|
|
22
|
+
* The fully resolved internal configuration for the SDK.
|
|
23
|
+
* @internal
|
|
24
|
+
*/
|
|
25
|
+
export type InternalConfig = {
|
|
26
|
+
pollingIntervalMs: number;
|
|
27
|
+
requestTimeoutMs: number;
|
|
28
|
+
};
|
|
29
|
+
/**
|
|
30
|
+
* Implementation of the main JulesClient interface.
|
|
31
|
+
* This class acts as the central hub for creating and managing sessions,
|
|
32
|
+
* as well as accessing other resources like sources.
|
|
33
|
+
*/
|
|
34
|
+
export declare class JulesClientImpl implements JulesClient {
|
|
35
|
+
/**
|
|
36
|
+
* Manages source connections (e.g., GitHub repositories).
|
|
37
|
+
*/
|
|
38
|
+
sources: SourceManager;
|
|
39
|
+
readonly storage: SessionStorage;
|
|
40
|
+
private apiClient;
|
|
41
|
+
private config;
|
|
42
|
+
private options;
|
|
43
|
+
private storageFactory;
|
|
44
|
+
private platform;
|
|
45
|
+
/**
|
|
46
|
+
* Lock to prevent concurrent sync operations.
|
|
47
|
+
* Using a simple boolean for in-process locking.
|
|
48
|
+
*/
|
|
49
|
+
private syncInProgress;
|
|
50
|
+
/**
|
|
51
|
+
* Creates a new instance of the JulesClient.
|
|
52
|
+
*
|
|
53
|
+
* @param options Configuration options for the client.
|
|
54
|
+
* @param defaultStorageFactory Factory for creating storage instances.
|
|
55
|
+
* @param defaultPlatform Platform-specific implementation.
|
|
56
|
+
*/
|
|
57
|
+
constructor(options: JulesOptions | undefined, defaultStorageFactory: StorageFactory, defaultPlatform: Platform);
|
|
58
|
+
/**
|
|
59
|
+
* Fluent API for rich local querying across sessions and activities.
|
|
60
|
+
* This method uses the modular query engine internally.
|
|
61
|
+
*/
|
|
62
|
+
select<T extends JulesDomain>(query: JulesQuery<T>): Promise<QueryResult<T>[]>;
|
|
63
|
+
/**
|
|
64
|
+
* Synchronizes local state with the server.
|
|
65
|
+
* Logic:
|
|
66
|
+
* 1. Find High-Water Mark (newest local record).
|
|
67
|
+
* 2. Stream latest sessions from API.
|
|
68
|
+
* 3. Terminate stream early if 'incremental' and High-Water Mark is hit.
|
|
69
|
+
* 4. Throttled hydration of activities if depth is 'activities'.
|
|
70
|
+
*/
|
|
71
|
+
sync(options?: SyncOptions): Promise<SyncStats>;
|
|
72
|
+
private getCheckpointPath;
|
|
73
|
+
private loadCheckpoint;
|
|
74
|
+
private saveCheckpoint;
|
|
75
|
+
private clearCheckpoint;
|
|
76
|
+
private _getHighWaterMark;
|
|
77
|
+
/**
|
|
78
|
+
* Helper to resolve environment variables with support for frontend prefixes.
|
|
79
|
+
*/
|
|
80
|
+
private getEnv;
|
|
81
|
+
/**
|
|
82
|
+
* Creates a new Jules client instance with updated configuration.
|
|
83
|
+
* This is an immutable operation; the original client instance remains unchanged.
|
|
84
|
+
*
|
|
85
|
+
* @param options The new configuration options to merge with the existing ones.
|
|
86
|
+
* @returns A new JulesClient instance with the updated configuration.
|
|
87
|
+
*/
|
|
88
|
+
with(options: JulesOptions): JulesClient;
|
|
89
|
+
/**
|
|
90
|
+
* Connects to the Jules service with the provided configuration.
|
|
91
|
+
* Acts as a factory method for creating a new client instance.
|
|
92
|
+
*
|
|
93
|
+
* @param options Configuration options for the client.
|
|
94
|
+
* @returns A new JulesClient instance.
|
|
95
|
+
*/
|
|
96
|
+
connect(options: JulesOptions): JulesClient;
|
|
97
|
+
/**
|
|
98
|
+
* Retrieves a session resource using the "Iceberg" caching strategy.
|
|
99
|
+
* * - **Tier 3 (Frozen):** > 30 days old. Returns from cache immediately.
|
|
100
|
+
* - **Tier 2 (Warm):** Terminal state + Verified < 24h ago. Returns from cache.
|
|
101
|
+
* - **Tier 1 (Hot):** Active or Stale. Fetches from network, updates cache, returns.
|
|
102
|
+
*/
|
|
103
|
+
getSessionResource(id: string): Promise<SessionResource>;
|
|
104
|
+
/**
|
|
105
|
+
* Lists sessions with a fluent, pagination-friendly API.
|
|
106
|
+
* @param options Configuration for pagination (pageSize, limit, pageToken)
|
|
107
|
+
* @returns A SessionCursor that can be awaited (first page) or iterated (all pages).
|
|
108
|
+
*/
|
|
109
|
+
sessions(options?: ListSessionsOptions): SessionCursor;
|
|
110
|
+
all<T>(items: T[], mapper: (item: T) => SessionConfig | Promise<SessionConfig>, options?: {
|
|
111
|
+
concurrency?: number;
|
|
112
|
+
stopOnError?: boolean;
|
|
113
|
+
delayMs?: number;
|
|
114
|
+
}): Promise<AutomatedSession[]>;
|
|
115
|
+
private _prepareSessionCreation;
|
|
116
|
+
/**
|
|
117
|
+
* Executes a task in automated mode.
|
|
118
|
+
* This is a high-level abstraction for "fire-and-forget" tasks.
|
|
119
|
+
*
|
|
120
|
+
* **Side Effects:**
|
|
121
|
+
* - Creates a new session on the Jules API (`POST /sessions`).
|
|
122
|
+
* - Initiates background polling for activity updates.
|
|
123
|
+
* - May create a Pull Request if `autoPr` is true (default).
|
|
124
|
+
*
|
|
125
|
+
* **Data Transformation:**
|
|
126
|
+
* - Resolves the `github` source identifier (e.g., `owner/repo`) to a full resource name.
|
|
127
|
+
* - Defaults `requirePlanApproval` to `false` for automated runs.
|
|
128
|
+
*
|
|
129
|
+
* @param config The configuration for the run.
|
|
130
|
+
* @returns A `AutomatedSession` object, which is an enhanced Promise that resolves to the final outcome.
|
|
131
|
+
* @throws {SourceNotFoundError} If the specified GitHub repository cannot be found or accessed.
|
|
132
|
+
* @throws {JulesApiError} If the session creation fails (e.g., 401 Unauthorized).
|
|
133
|
+
*
|
|
134
|
+
* @example
|
|
135
|
+
* const run = await jules.run({
|
|
136
|
+
* prompt: "Fix the login bug",
|
|
137
|
+
* source: { github: "my-org/repo", baseBranch: "main" }
|
|
138
|
+
* });
|
|
139
|
+
* const outcome = await run.result();
|
|
140
|
+
*/
|
|
141
|
+
run(config: SessionConfig): Promise<AutomatedSession>;
|
|
142
|
+
/**
|
|
143
|
+
* Creates a new interactive session for workflows requiring human oversight.
|
|
144
|
+
*
|
|
145
|
+
* **Side Effects:**
|
|
146
|
+
* - Creates a new session on the Jules API (`POST /sessions`).
|
|
147
|
+
* - Initializes local storage for the session.
|
|
148
|
+
*
|
|
149
|
+
* **Data Transformation:**
|
|
150
|
+
* - Defaults `requirePlanApproval` to `true` for interactive sessions.
|
|
151
|
+
*
|
|
152
|
+
* @param config The configuration for the session.
|
|
153
|
+
* @returns A Promise resolving to the interactive `SessionClient`.
|
|
154
|
+
* @throws {SourceNotFoundError} If the source cannot be found.
|
|
155
|
+
*
|
|
156
|
+
* @example
|
|
157
|
+
* const session = await jules.session({
|
|
158
|
+
* prompt: "Let's explore the codebase",
|
|
159
|
+
* source: { github: "owner/repo", baseBranch: "main" }
|
|
160
|
+
* });
|
|
161
|
+
*/
|
|
162
|
+
session(config: SessionConfig): Promise<SessionClient>;
|
|
163
|
+
/**
|
|
164
|
+
* Rehydrates an existing session from its ID, allowing you to resume interaction.
|
|
165
|
+
* This is useful for stateless environments (like serverless functions) where you need to
|
|
166
|
+
* reconnect to a long-running session.
|
|
167
|
+
*
|
|
168
|
+
* **Side Effects:**
|
|
169
|
+
* - Initializes local storage for the existing session ID.
|
|
170
|
+
* - Does NOT make a network request immediately (lazy initialization).
|
|
171
|
+
*
|
|
172
|
+
* @param sessionId The ID of the existing session.
|
|
173
|
+
* @returns The interactive `SessionClient`.
|
|
174
|
+
*
|
|
175
|
+
* @example
|
|
176
|
+
* const session = jules.session("12345");
|
|
177
|
+
* const info = await session.info(); // Now makes a request
|
|
178
|
+
*/
|
|
179
|
+
session(sessionId: string): SessionClient;
|
|
180
|
+
}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Copyright 2026 Google LLC
|
|
3
|
+
*
|
|
4
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
* you may not use this file except in compliance with the License.
|
|
6
|
+
* You may obtain a copy of the License at
|
|
7
|
+
*
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
*
|
|
10
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
* See the License for the specific language governing permissions and
|
|
14
|
+
* limitations under the License.
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* Base class for all SDK-specific errors.
|
|
18
|
+
* This allows consumers to catch all Jules SDK errors with a single `catch` block.
|
|
19
|
+
*/
|
|
20
|
+
export declare class JulesError extends Error {
|
|
21
|
+
/** The original error that caused this error, if any. */
|
|
22
|
+
readonly cause?: Error;
|
|
23
|
+
constructor(message: string, options?: {
|
|
24
|
+
cause?: Error;
|
|
25
|
+
});
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Thrown for fundamental network issues like fetch failures or timeouts.
|
|
29
|
+
*/
|
|
30
|
+
export declare class JulesNetworkError extends JulesError {
|
|
31
|
+
readonly url: string;
|
|
32
|
+
constructor(url: string, options?: {
|
|
33
|
+
cause?: Error;
|
|
34
|
+
});
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* A generic wrapper for non-2xx API responses that don't match other specific errors.
|
|
38
|
+
*/
|
|
39
|
+
export declare class JulesApiError extends JulesError {
|
|
40
|
+
readonly url: string;
|
|
41
|
+
readonly status: number;
|
|
42
|
+
readonly statusText: string;
|
|
43
|
+
constructor(url: string, status: number, statusText: string, message?: string, // optional override
|
|
44
|
+
options?: {
|
|
45
|
+
cause?: Error;
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Thrown for 401 Unauthorized or 403 Forbidden API responses.
|
|
50
|
+
*/
|
|
51
|
+
export declare class JulesAuthenticationError extends JulesApiError {
|
|
52
|
+
constructor(url: string, status: number, statusText: string);
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Thrown for 429 Too Many Requests API responses.
|
|
56
|
+
*/
|
|
57
|
+
export declare class JulesRateLimitError extends JulesApiError {
|
|
58
|
+
constructor(url: string, status: number, statusText: string);
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Thrown when an API key is required but not provided.
|
|
62
|
+
*/
|
|
63
|
+
export declare class MissingApiKeyError extends JulesError {
|
|
64
|
+
constructor();
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Thrown when a requested source cannot be found.
|
|
68
|
+
*/
|
|
69
|
+
export declare class SourceNotFoundError extends JulesError {
|
|
70
|
+
constructor(sourceIdentifier: string);
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Thrown when a jules.run() operation terminates in a FAILED state.
|
|
74
|
+
*/
|
|
75
|
+
export declare class AutomatedSessionFailedError extends JulesError {
|
|
76
|
+
constructor(reason?: string);
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Thrown when an operation exceeds its specified timeout.
|
|
80
|
+
*/
|
|
81
|
+
export declare class TimeoutError extends JulesError {
|
|
82
|
+
constructor(message: string);
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Thrown when attempting to start a sync while another sync is already in progress.
|
|
86
|
+
* This prevents data corruption and thundering herd issues.
|
|
87
|
+
*/
|
|
88
|
+
export declare class SyncInProgressError extends JulesError {
|
|
89
|
+
constructor();
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Thrown when an operation is attempted on a session that is not in a
|
|
93
|
+
* valid state for that operation.
|
|
94
|
+
*/
|
|
95
|
+
export declare class InvalidStateError extends JulesError {
|
|
96
|
+
constructor(message: string);
|
|
97
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Copyright 2026 Google LLC
|
|
3
|
+
*
|
|
4
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
* you may not use this file except in compliance with the License.
|
|
6
|
+
* You may obtain a copy of the License at
|
|
7
|
+
*
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
*
|
|
10
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
* See the License for the specific language governing permissions and
|
|
14
|
+
* limitations under the License.
|
|
15
|
+
*/
|
|
16
|
+
import { JulesClient, JulesOptions } from './types.js';
|
|
17
|
+
/**
|
|
18
|
+
* Connects to the Jules service using Node.js defaults (File System, Native Crypto).
|
|
19
|
+
* Acts as a factory method for creating a new client instance.
|
|
20
|
+
*
|
|
21
|
+
* @param options Configuration options for the client.
|
|
22
|
+
* @returns A new JulesClient instance.
|
|
23
|
+
*/
|
|
24
|
+
export declare function connect(options?: JulesOptions): JulesClient;
|
|
25
|
+
/**
|
|
26
|
+
* The main entry point for the Jules SDK.
|
|
27
|
+
* This is a pre-initialized client that can be used immediately with default settings
|
|
28
|
+
* (e.g., reading API keys from environment variables).
|
|
29
|
+
*
|
|
30
|
+
* @example
|
|
31
|
+
* import { jules } from '@google/jules-sdk';
|
|
32
|
+
* const session = await jules.session({ ... });
|
|
33
|
+
*/
|
|
34
|
+
export declare const jules: JulesClient;
|
|
35
|
+
export * from './errors.js';
|
|
36
|
+
export type { Activity, ActivityAgentMessaged, ActivityPlanApproved, ActivityPlanGenerated, ActivityProgressUpdated, ActivitySummary, ActivitySessionCompleted, ActivitySessionFailed, ActivityUserMessaged, Artifact, AutomatedSession, ChangeSet, GitHubRepo, GitPatch, JulesClient, JulesOptions, LightweightActivity, LightweightArtifact, MediaArtifact, SessionOutcome as Outcome, ParsedChangeSet, ParsedFile, Plan, PlanStep, PullRequest, SessionClient, SessionConfig, SessionOutput, SessionResource, SessionState, Source, SourceContext, SourceInput, SourceManager, StrippedMediaArtifact, JulesQuery, JulesDomain, SyncDepth, SerializedSnapshot, SnapshotField, ToJSONOptions, } from './types.js';
|
|
37
|
+
export { SESSION_SCHEMA, ACTIVITY_SCHEMA, FILTER_OP_SCHEMA, PROJECTION_SCHEMA, getSchema, getAllSchemas, generateTypeDefinition, generateMarkdownDocs, } from './query/schema.js';
|
|
38
|
+
export type { FieldMeta, DomainSchema, QueryExample } from './query/schema.js';
|
|
39
|
+
export { validateQuery, formatValidationResult } from './query/validate.js';
|
|
40
|
+
export type { ValidationError, ValidationWarning, ValidationResult, ValidationErrorCode, } from './query/validate.js';
|
|
41
|
+
export { SessionCursor } from './sessions.js';
|
|
42
|
+
export type { ListSessionsOptions, ListSessionsResponse } from './sessions.js';
|
|
43
|
+
export { toSummary } from './activities/summary.js';
|
|
44
|
+
export { JulesClientImpl } from './client.js';
|
|
45
|
+
export { MemoryStorage, MemorySessionStorage } from './storage/memory.js';
|
|
46
|
+
export { NodePlatform } from './platform/node.js';
|
|
47
|
+
export type { Platform } from './platform/types.js';
|
|
48
|
+
export type { StorageFactory } from './types.js';
|
|
49
|
+
export { ChangeSetArtifact, BashArtifact, parseUnidiff } from './artifacts.js';
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Copyright 2026 Google LLC
|
|
3
|
+
*
|
|
4
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
* you may not use this file except in compliance with the License.
|
|
6
|
+
* You may obtain a copy of the License at
|
|
7
|
+
*
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
*
|
|
10
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
* See the License for the specific language governing permissions and
|
|
14
|
+
* limitations under the License.
|
|
15
|
+
*/
|
|
16
|
+
import { Activity, Artifact, SessionOutcome, RestArtifact, SessionResource, RestSessionResource, RestSessionOutput, RestSource, SessionOutput, Source, SessionState } from './types.js';
|
|
17
|
+
/**
|
|
18
|
+
* Maps a raw REST API Artifact resource to the SDK's `Artifact` type.
|
|
19
|
+
* This now instantiates rich classes for certain artifact types.
|
|
20
|
+
*
|
|
21
|
+
* @param restArtifact The raw artifact object from the REST API.
|
|
22
|
+
* @returns A structured `Artifact` object for the SDK.
|
|
23
|
+
* @internal
|
|
24
|
+
*/
|
|
25
|
+
export declare function mapRestArtifactToSdkArtifact(restArtifact: RestArtifact, platform: any, activityId?: string): Artifact;
|
|
26
|
+
/**
|
|
27
|
+
* Maps a raw REST API Activity resource to the SDK's discriminated union `Activity` type.
|
|
28
|
+
*
|
|
29
|
+
* **Data Transformation:**
|
|
30
|
+
* - Flattens nested union fields (e.g., `agentMessaged`) into a top-level `type` property.
|
|
31
|
+
* - Extracts the short ID from the full resource `name`.
|
|
32
|
+
* - Recursively maps all artifacts within the activity.
|
|
33
|
+
*
|
|
34
|
+
* @param restActivity The raw activity object from the REST API.
|
|
35
|
+
* @param platform The platform adapter (needed for artifact mapping).
|
|
36
|
+
* @returns A structured `Activity` object for the SDK.
|
|
37
|
+
* @throws {Error} If the activity type is unknown.
|
|
38
|
+
* @internal
|
|
39
|
+
*/
|
|
40
|
+
export declare function mapRestActivityToSdkActivity(restActivity: any, platform: any): Activity;
|
|
41
|
+
export declare function mapRestStateToSdkState(state: string): SessionState;
|
|
42
|
+
export declare function mapRestSourceToSdkSource(rest: RestSource): Source;
|
|
43
|
+
export declare function mapRestOutputToSdkOutput(rest: RestSessionOutput): SessionOutput;
|
|
44
|
+
export declare function mapRestSessionToSdkSession(rest: RestSessionResource, platform?: any): SessionResource;
|
|
45
|
+
/**
|
|
46
|
+
* Maps the final state of a SessionResource to a user-facing Outcome object.
|
|
47
|
+
* This includes extracting the primary pull request and handling the failed state.
|
|
48
|
+
*
|
|
49
|
+
* @param session The final SessionResource from the API.
|
|
50
|
+
* @returns The corresponding Outcome object.
|
|
51
|
+
* @throws {AutomatedSessionFailedError} If the session state is 'failed'.
|
|
52
|
+
*/
|
|
53
|
+
export declare function mapSessionResourceToOutcome(session: SessionResource): SessionOutcome;
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Copyright 2026 Google LLC
|
|
3
|
+
*
|
|
4
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
* you may not use this file except in compliance with the License.
|
|
6
|
+
* You may obtain a copy of the License at
|
|
7
|
+
*
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
*
|
|
10
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
* See the License for the specific language governing permissions and
|
|
14
|
+
* limitations under the License.
|
|
15
|
+
*/
|
|
16
|
+
import { ApiClient } from '../api.js';
|
|
17
|
+
import { NetworkClient } from '../activities/client.js';
|
|
18
|
+
import { Activity } from '../types.js';
|
|
19
|
+
import { ListOptions } from '../activities/types.js';
|
|
20
|
+
import { Platform } from '../platform/types.js';
|
|
21
|
+
/**
|
|
22
|
+
* Concrete implementation of NetworkClient that communicates with the Jules API.
|
|
23
|
+
* Handles fetching activities and streaming them via polling.
|
|
24
|
+
*/
|
|
25
|
+
export declare class NetworkAdapter implements NetworkClient {
|
|
26
|
+
private apiClient;
|
|
27
|
+
private sessionId;
|
|
28
|
+
private pollingIntervalMs;
|
|
29
|
+
private platform;
|
|
30
|
+
constructor(apiClient: ApiClient, sessionId: string, pollingIntervalMs: number | undefined, platform: Platform);
|
|
31
|
+
/**
|
|
32
|
+
* Fetches a single activity from the API.
|
|
33
|
+
*/
|
|
34
|
+
fetchActivity(activityId: string): Promise<Activity>;
|
|
35
|
+
/**
|
|
36
|
+
* Lists activities from the API with pagination.
|
|
37
|
+
*/
|
|
38
|
+
listActivities(options?: ListOptions): Promise<{
|
|
39
|
+
activities: Activity[];
|
|
40
|
+
nextPageToken?: string;
|
|
41
|
+
}>;
|
|
42
|
+
/**
|
|
43
|
+
* Polls the API for new activities and yields them.
|
|
44
|
+
* This stream never ends unless the process is terminated.
|
|
45
|
+
*/
|
|
46
|
+
rawStream(): AsyncIterable<Activity>;
|
|
47
|
+
}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Copyright 2026 Google LLC
|
|
3
|
+
*
|
|
4
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
* you may not use this file except in compliance with the License.
|
|
6
|
+
* You may obtain a copy of the License at
|
|
7
|
+
*
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
*
|
|
10
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
* See the License for the specific language governing permissions and
|
|
14
|
+
* limitations under the License.
|
|
15
|
+
*/
|
|
16
|
+
import { Platform, PlatformResponse } from './types.js';
|
|
17
|
+
/**
|
|
18
|
+
* Node.js implementation of the Platform interface.
|
|
19
|
+
*/
|
|
20
|
+
export declare class NodePlatform implements Platform {
|
|
21
|
+
/**
|
|
22
|
+
* Saves a file to the local filesystem using `node:fs/promises`.
|
|
23
|
+
*
|
|
24
|
+
* **Side Effects:**
|
|
25
|
+
* - Writes a file to disk.
|
|
26
|
+
* - Overwrites the file if it already exists.
|
|
27
|
+
*/
|
|
28
|
+
saveFile(filepath: string, data: string, encoding: 'base64', activityId?: string): Promise<void>;
|
|
29
|
+
sleep(ms: number): Promise<void>;
|
|
30
|
+
createDataUrl(data: string, mimeType: string): string;
|
|
31
|
+
fetch(input: string, init?: any): Promise<PlatformResponse>;
|
|
32
|
+
crypto: {
|
|
33
|
+
randomUUID: () => `${string}-${string}-${string}-${string}-${string}`;
|
|
34
|
+
sign(text: string, secret: string): Promise<string>;
|
|
35
|
+
verify(text: string, signature: string, secret: string): Promise<boolean>;
|
|
36
|
+
};
|
|
37
|
+
encoding: {
|
|
38
|
+
base64Encode: (text: string) => string;
|
|
39
|
+
base64Decode: (text: string) => string;
|
|
40
|
+
};
|
|
41
|
+
getEnv(key: string): string | undefined;
|
|
42
|
+
readFile(path: string): Promise<string>;
|
|
43
|
+
writeFile(path: string, content: string): Promise<void>;
|
|
44
|
+
deleteFile(path: string): Promise<void>;
|
|
45
|
+
}
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Copyright 2026 Google LLC
|
|
3
|
+
*
|
|
4
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
* you may not use this file except in compliance with the License.
|
|
6
|
+
* You may obtain a copy of the License at
|
|
7
|
+
*
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
*
|
|
10
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
* See the License for the specific language governing permissions and
|
|
14
|
+
* limitations under the License.
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* A unified response interface that works across Node, Browser, and GAS.
|
|
18
|
+
*/
|
|
19
|
+
export interface PlatformResponse {
|
|
20
|
+
ok: boolean;
|
|
21
|
+
status: number;
|
|
22
|
+
json<T = any>(): Promise<T>;
|
|
23
|
+
text(): Promise<string>;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Abstract interface for platform-specific functionality.
|
|
27
|
+
* Allows the SDK to run in both Node.js, browser, and Google Apps Script environments.
|
|
28
|
+
*/
|
|
29
|
+
export interface Platform {
|
|
30
|
+
/**
|
|
31
|
+
* Saves a file to the platform's filesystem.
|
|
32
|
+
*/
|
|
33
|
+
saveFile(filepath: string, data: string, encoding: 'base64', activityId?: string): Promise<void>;
|
|
34
|
+
/**
|
|
35
|
+
* Pauses execution for the specified duration.
|
|
36
|
+
*/
|
|
37
|
+
sleep(ms: number): Promise<void>;
|
|
38
|
+
/**
|
|
39
|
+
* Creates a data URL for the given data.
|
|
40
|
+
*/
|
|
41
|
+
createDataUrl(data: string, mimeType: string): string;
|
|
42
|
+
/**
|
|
43
|
+
* Unified network fetch.
|
|
44
|
+
*/
|
|
45
|
+
fetch(input: string, init?: any): Promise<PlatformResponse>;
|
|
46
|
+
/**
|
|
47
|
+
* Unified crypto operations.
|
|
48
|
+
*/
|
|
49
|
+
crypto: {
|
|
50
|
+
/**
|
|
51
|
+
* Generates a standard UUID v4.
|
|
52
|
+
*/
|
|
53
|
+
randomUUID(): string;
|
|
54
|
+
/**
|
|
55
|
+
* Signs a string using HMAC-SHA256 and returns a Base64Url encoded string.
|
|
56
|
+
* Used for minting Capability Tokens.
|
|
57
|
+
*/
|
|
58
|
+
sign(text: string, secret: string): Promise<string>;
|
|
59
|
+
/**
|
|
60
|
+
* Verifies a signature.
|
|
61
|
+
*/
|
|
62
|
+
verify(text: string, signature: string, secret: string): Promise<boolean>;
|
|
63
|
+
};
|
|
64
|
+
/**
|
|
65
|
+
* Unified encoding/decoding operations.
|
|
66
|
+
*/
|
|
67
|
+
encoding: {
|
|
68
|
+
/**
|
|
69
|
+
* Encodes a string to Base64URL format.
|
|
70
|
+
* (URL-safe: '-' instead of '+', '_' instead of '/', no padding)
|
|
71
|
+
*/
|
|
72
|
+
base64Encode(text: string): string;
|
|
73
|
+
/**
|
|
74
|
+
* Decodes a Base64URL encoded string.
|
|
75
|
+
*/
|
|
76
|
+
base64Decode(text: string): string;
|
|
77
|
+
};
|
|
78
|
+
/**
|
|
79
|
+
* Retrieves an environment variable or configuration value.
|
|
80
|
+
*
|
|
81
|
+
* @param key The name of the environment variable (e.g., "JULES_API_KEY").
|
|
82
|
+
* @returns The value of the environment variable, or `undefined` if not set.
|
|
83
|
+
*/
|
|
84
|
+
getEnv(key: string): string | undefined;
|
|
85
|
+
readFile?(path: string): Promise<string>;
|
|
86
|
+
writeFile?(path: string, content: string): Promise<void>;
|
|
87
|
+
deleteFile?(path: string): Promise<void>;
|
|
88
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Copyright 2026 Google LLC
|
|
3
|
+
*
|
|
4
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
* you may not use this file except in compliance with the License.
|
|
6
|
+
* You may obtain a copy of the License at
|
|
7
|
+
*
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
*
|
|
10
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
* See the License for the specific language governing permissions and
|
|
14
|
+
* limitations under the License.
|
|
15
|
+
*/
|
|
16
|
+
import { ApiClient } from './api.js';
|
|
17
|
+
import { SessionResource } from './types.js';
|
|
18
|
+
/**
|
|
19
|
+
* A generalized utility for polling the session resource until a specific
|
|
20
|
+
* condition is met.
|
|
21
|
+
*
|
|
22
|
+
* @param sessionId The ID of the session to poll.
|
|
23
|
+
* @param apiClient The API client for making requests.
|
|
24
|
+
* @param predicateFn A function that returns `true` if polling should stop.
|
|
25
|
+
* @param pollingInterval The interval in milliseconds between poll attempts.
|
|
26
|
+
* @param timeoutMs The maximum duration in milliseconds to poll before timing out.
|
|
27
|
+
* @returns The session resource that satisfied the predicate.
|
|
28
|
+
* @throws {TimeoutError} If the timeout is exceeded.
|
|
29
|
+
* @internal
|
|
30
|
+
*/
|
|
31
|
+
export declare function pollSession(sessionId: string, apiClient: ApiClient, predicateFn: (session: SessionResource) => boolean, pollingInterval: number, platform: any, timeoutMs?: number): Promise<SessionResource>;
|
|
32
|
+
/**
|
|
33
|
+
* Polls the `GET /sessions/{id}` endpoint until the session reaches a terminal state.
|
|
34
|
+
*
|
|
35
|
+
* @param sessionId The ID of the session to poll.
|
|
36
|
+
* @param apiClient The API client for making requests.
|
|
37
|
+
* @param pollingInterval The interval in milliseconds between poll attempts.
|
|
38
|
+
* @param timeoutMs The maximum duration in milliseconds to poll before timing out.
|
|
39
|
+
* @returns The final SessionResource.
|
|
40
|
+
* @throws {TimeoutError} If the timeout is exceeded.
|
|
41
|
+
* @internal
|
|
42
|
+
*/
|
|
43
|
+
export declare function pollUntilCompletion(sessionId: string, apiClient: ApiClient, pollingInterval: number, platform: any, timeoutMs?: number): Promise<SessionResource>;
|