reconcile: merge 11 fleet SDK example PRs (248-259)

packages/core/README.md

@@ -11,6 +11,17 @@ Orchestrate complex, long-running coding tasks to an ephemeral cloud environment
 - [Agent Workflow](./examples/agent/README.md)
 - [Webhook Integration](./examples/webhook/README.md)
 - [GitHub Actions](./examples/github-actions/README.md)
+- [Ai Sdk Integration](./examples/ai-sdk/README.md)
+- [Nextjs Integration](./examples/nextjs/README.md)
+- [Custom Mcp Server](./examples/custom-mcp-server/README.md)
+- [Custom Cli Tools](./examples/custom-cli/README.md)
+- [Github Action Agentskills](./examples/github-action-agentskills/README.md)
+- [Gitpatch Improve](./examples/gitpatch-improve/README.md)
+- [Google Sheets Context](./examples/google-sheets/README.md)
+- [Cloudflare Workers](./examples/cloudflare-workers/README.md)
+- [Gitpatch Goals](./examples/gitpatch-goals/README.md)
+- [Gitpatch Review](./examples/gitpatch-review/README.md)
+- [Gitpatch Local](./examples/gitpatch-local/README.md)
 
 ## Send work to a Cloud based session
 
@@ -324,3 +335,4 @@ Apache-2.0
 
 > **Note:** This is not an officially supported Google product. This project is not eligible for the [Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security).
 
+

packages/core/examples/ai-sdk/CONTEXT.md

@@ -0,0 +1,13 @@
+# Agent Context Guidelines
+
+This file is explicitly for AI/LLM Agents acting as operators or integrators against this CLI.
+
+## Overview
+
+You are invoking the `ai-sdk-example` CLI. This CLI adheres to Agent DX best practices to ensure predictability and defense-in-depth logic. You are interacting with the entrypoints, primarily the `start` command.
+
+## Invariants
+
+1. **Output formatting:** Always specify `--output json` when executing the CLI to guarantee machine-readable output rather than human-readable text. Do not rely on stdout text parsing.
+2. **Mutations:** Jules sessions represent large, complex mutating cloud tasks. If you are verifying parameters, assessing feasibility, or unsure about an input string, ALWAYS run `--dry-run` first to test the system boundary.
+3. **Adversarial inputs:** Be aware that the `JulesCodingTaskSpec` strict schema parsing handles your inputs. Path traversals (`../`), query strings (`?`), fragments (`#`), control chars, or pre-URL encoded characters will be strictly rejected. Ensure the inputs are clean before calling the tool.

packages/core/examples/ai-sdk/README.md

@@ -0,0 +1,44 @@
+# Vercel AI SDK Integration Example (Agent DX CLI)
+
+This example demonstrates how to integrate the Jules SDK with the Vercel AI SDK to provide AI-powered coding capabilities within an AI application.
+
+Following **Agent DX best practices**, this example is packaged as a CLI built with `citty`. It utilizes the `generateText` function from the `ai` package and Google's `gemini-3.1-flash-lite-preview` model.
+
+The AI is given a composable, isolated tool called `executeCodingTask` that internally uses the Jules SDK to spin up a cloud environment and perform complex coding tasks. The tool is implemented using the **Typed Service Contract** pattern, providing rigorous type safety, input parsing (via Zod), and explicit error handling (Result Pattern).
+
+## Prerequisites
+
+- Node.js or Bun installed.
+- A Jules API Key. Set it using:
+  ```bash
+  export JULES_API_KEY=<your-api-key>
+  ```
+- A Google Generative AI API Key. Set it using:
+  ```bash
+  export GOOGLE_GENERATIVE_AI_API_KEY=<your-google-api-key>
+  ```
+
+## Running the Example
+
+You can run this example using `bun`:
+
+### Standard Human-Friendly Output
+```bash
+bun start start --prompt "Fix visibility issues by changing background colors to a zinc palette." --repo "your-org/your-repo"
+```
+
+### Agent-Friendly JSON Output (Agent DX)
+```bash
+bun start start --prompt "Fix visibility issues." --output json
+```
+
+## Architecture
+
+This project is structured for predictability and minimizing merge conflicts:
+
+1.  **CLI Entrypoint (`src/cli.ts`)**: Minimal registration boundary built with `citty`. It lazily registers subcommands (e.g. `start`) to avoid central hotspots as the CLI scales.
+2.  **Command Modules (`src/commands/*.ts`)**: Isolated entrypoints for flags, CLI argument parsing, environment variable logic checks, and selecting the output format (`--output json`).
+3.  **Services (`src/services/agent.ts`)**: Encapsulates the Vercel AI SDK logic (`generateText` with `@ai-sdk/google`) to abstract the specific LLM interactions away from the CLI layer.
+4.  **Tool Spec (`src/tools/jules-coding-task/spec.ts`)**: The Contract boundary. Parses tool input using Zod and defines a strict `Result` return type.
+5.  **Tool Handler (`src/tools/jules-coding-task/handler.ts`)**: The impure business logic. It initiates `jules.session()`, waits for the session to complete, and evaluates the `session.result()`. It *never* throws errors.
+6.  **Tool Wrapper (`src/tools/jules-coding-task/index.ts`)**: Maps the typed contract into a standard Vercel AI SDK `tool()` wrapper.

packages/core/examples/ai-sdk/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "ai-sdk-example",
+  "version": "1.0.0",
+  "description": "An example integrating Vercel AI SDK with Jules SDK",
+  "type": "module",
+  "scripts": {
+    "start": "bun run src/cli.ts"
+  },
+  "dependencies": {
+    "@ai-sdk/google": "^1.1.17",
+    "@google/jules-sdk": "workspace:*",
+    "ai": "^4.1.45",
+    "citty": "^0.1.6",
+    "zod": "^3.24.2"
+  }
+}

packages/core/examples/ai-sdk/src/cli.ts

@@ -0,0 +1,15 @@
+import { defineCommand, runMain } from 'citty';
+
+const main = defineCommand({
+  meta: {
+    name: 'ai-sdk-example',
+    version: '1.0.0',
+    description:
+      'A CLI demonstrating Vercel AI SDK integration with Jules SDK using Agent DX principles.',
+  },
+  subCommands: {
+    start: () => import('./commands/start.js').then((m) => m.default),
+  },
+});
+
+runMain(main);

packages/core/examples/ai-sdk/src/commands/start.ts

@@ -0,0 +1,91 @@
+import { defineCommand } from 'citty';
+import { runAgent } from '../services/agent.js';
+
+export default defineCommand({
+  meta: {
+    name: 'start',
+    description: 'Start an agent session to handle a coding prompt.',
+  },
+  args: {
+    prompt: {
+      type: 'string',
+      description: 'The coding prompt to feed the AI.',
+      required: true,
+    },
+    output: {
+      type: 'string',
+      description: 'Output format (json or text). Use json for agents.',
+      default: 'text',
+    },
+    repo: {
+      type: 'string',
+      description: 'Optional GitHub repository (e.g. "owner/repo").',
+      required: false,
+    },
+    'dry-run': {
+      type: 'boolean',
+      description: 'Validate input and logic without creating a real cloud session.',
+      default: false,
+    },
+  },
+  async run({ args }) {
+    // 1. Logic Checks: Validate Environment Context explicitly before attempting external operations
+    if (!process.env.JULES_API_KEY) {
+      console.error('Error: JULES_API_KEY environment variable is missing.');
+      process.exit(1);
+    }
+
+    if (!process.env.GOOGLE_GENERATIVE_AI_API_KEY) {
+      console.error('Error: GOOGLE_GENERATIVE_AI_API_KEY environment variable is missing.');
+      process.exit(1);
+    }
+
+    // 2. Encapsulate execution in the service abstraction
+    const response = await runAgent({
+      prompt: args.prompt,
+      repo: args.repo,
+      dryRun: args['dry-run'],
+    });
+
+    // 3. Render payload strictly conforming to output format expectation (Agent DX vs Human)
+    if (args.output === 'json') {
+      if (response.success) {
+        console.log(
+          JSON.stringify(
+            {
+              success: true,
+              result: response.result,
+              toolCalls: response.toolCalls,
+            },
+            null,
+            2,
+          ),
+        );
+      } else {
+        console.error(
+          JSON.stringify(
+            {
+              success: false,
+              error: response.error,
+            },
+            null,
+            2,
+          ),
+        );
+        process.exit(1);
+      }
+    } else {
+      if (response.success) {
+        console.log('\n--- Final Response from AI ---');
+        console.log(response.result);
+        if (response.toolCalls && response.toolCalls.length > 0) {
+          console.log('\n--- Tools Invoked ---');
+          response.toolCalls.forEach((c) => console.log(`- ${c.name}`));
+        }
+      } else {
+        console.error('Execution Failed:', response.error);
+        process.exit(1);
+      }
+    }
+  },
+});

packages/core/examples/ai-sdk/src/services/agent.ts

@@ -0,0 +1,51 @@
+import { generateText } from 'ai';
+import { google } from '@ai-sdk/google';
+import { executeCodingTask } from '../tools/jules-coding-task/index.js';
+
+export interface AgentRequest {
+  prompt: string;
+  repo?: string;
+  dryRun?: boolean;
+}
+
+export interface AgentResponse {
+  success: boolean;
+  result?: string;
+  toolCalls?: Array<{ name: string; args: any }>;
+  error?: string;
+}
+
+/**
+ * Encapsulates the Vercel AI SDK logic.
+ * This service handles calling the LLM and managing available tools.
+ */
+export async function runAgent(request: AgentRequest): Promise<AgentResponse> {
+  const contextPrompt = request.repo
+    ? `Task: ${request.prompt}\nContext: Apply this task to the repository "${request.repo}".`
+    : `Task: ${request.prompt}`;
+
+  try {
+    const { text, toolCalls } = await generateText({
+      model: google('gemini-3.1-flash-lite-preview'),
+      system: request.dryRun
+        ? "You are in dry-run mode. ALWAYS pass dryRun: true to any tools you execute."
+        : "",
+      prompt: contextPrompt,
+      tools: {
+        executeCodingTask,
+      },
+      maxSteps: 2,
+    });
+
+    return {
+      success: true,
+      result: text,
+      toolCalls: toolCalls?.map((c) => ({ name: c.toolName, args: c.args })) || [],
+    };
+  } catch (error: any) {
+    return {
+      success: false,
+      error: error.message || String(error),
+    };
+  }
+}