From b145bb79066a39d01b3f6b39724c3badaf83d4be Mon Sep 17 00:00:00 2001
From: davideast <4570265+davideast@users.noreply.github.com>
Date: Mon, 9 Mar 2026 20:57:58 +0000
Subject: [PATCH] Add advanced session example to the SDK documentation

This commit adds a new advanced session example showcasing interactive sessions, streaming activities, and handling artifacts (such as Bash Output and ChangeSet diffs).
Also updates the core package README to link to the new example.

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
---
 packages/core/README.md                       |  4 +
 .../core/examples/advanced-session/README.md  | 14 ++++
 .../core/examples/advanced-session/index.ts   | 81 +++++++++++++++++++
 3 files changed, 99 insertions(+)
 create mode 100644 packages/core/examples/advanced-session/README.md
 create mode 100644 packages/core/examples/advanced-session/index.ts

diff --git a/packages/core/README.md b/packages/core/README.md
index 48c4673..14b8345 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -4,6 +4,10 @@
 
 Orchestrate complex, long-running coding tasks to an ephemeral cloud environment integrated with a GitHub repo.
 
+## Examples
+
+- [Advanced Session](./examples/advanced-session/README.md)
+
 ## Send work to a Cloud based session
 
 ```ts
diff --git a/packages/core/examples/advanced-session/README.md b/packages/core/examples/advanced-session/README.md
new file mode 100644
index 0000000..6d7cbe3
--- /dev/null
+++ b/packages/core/examples/advanced-session/README.md
@@ -0,0 +1,14 @@
+# Advanced Session Example
+
+This example demonstrates how to use the Jules SDK to run a session, interact with it, wait for plan approvals, and monitor stream progress while parsing the output for artifacts.
+
+## Running
+
+Ensure you have your `JULES_API_KEY` set.
+You can run the script via:
+
+```sh
+bun run index.ts
+```
+
+This will run the advanced session and stream activities.
diff --git a/packages/core/examples/advanced-session/index.ts b/packages/core/examples/advanced-session/index.ts
new file mode 100644
index 0000000..cbfaeff
--- /dev/null
+++ b/packages/core/examples/advanced-session/index.ts
@@ -0,0 +1,81 @@
+import { jules, JulesError } from '@google/jules-sdk';
+
+/**
+ * Advanced Session Example
+ *
+ * Demonstrates:
+ * - Interactive session creation
+ * - Waiting for plan approval
+ * - Monitoring progress via reactive streams
+ * - Handling code diffs (changeSet)
+ */
+async function runAdvancedSession() {
+  try {
+    console.log('Starting advanced session...');
+
+    // Interactive Sessions allow you to provide feedback and guide the process
+    const session = await jules.session({
+      prompt: `Create a simple python script that prints 'Hello Advanced Session!' and test it.`,
+      // For a repoless session, we don't provide a source
+    });
+
+    console.log(`Session created: ${session.id}`);
+
+    // Wait for the plan to be generated and ready for approval
+    console.log('Waiting for plan approval...');
+    await session.waitFor('awaitingPlanApproval');
+
+    console.log('Plan is ready. Approving it now.');
+    await session.approve();
+
+    // Stream activities and artifacts
+    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 'progressUpdated':
+          console.log(`Progress: ${activity.title}`);
+          break;
+        case 'sessionCompleted':
+          console.log('Session complete!');
+          break;
+      }
+
+      // Check artifacts
+      for (const artifact of activity.artifacts ?? []) {
+        if (artifact.type === 'bashOutput') {
+          console.log(`[BASH] ${artifact.toString()}`);
+        }
+        if (artifact.type === 'changeSet') {
+          const parsed = artifact.parsed();
+          for (const file of parsed.files) {
+            console.log(
+              `[DIFF] ${file.path}: +${file.additions} -${file.deletions}`
+            );
+          }
+        }
+      }
+    }
+
+    const outcome = await session.result();
+    console.log(`Session finished with state: ${outcome.state}`);
+
+  } catch (error) {
+    if (error instanceof JulesError) {
+      console.error(`SDK error: ${error.message}`);
+    } else {
+      console.error('Unknown error:', error);
+    }
+  }
+}
+
+if (require.main === module) {
+  runAdvancedSession();
+}