@loopstack/oauth-examples 0.1.1

package/dist/workflows/google-workspace-agent/google-workspace-agent-example.workflow.js

@@ -0,0 +1,187 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoogleWorkspaceAgentExampleWorkflow = void 0;
+const node_path_1 = require("node:path");
+const zod_1 = require("zod");
+const common_1 = require("@loopstack/common");
+const google_workspace_module_1 = require("@loopstack/google-workspace-module");
+const llm_provider_module_1 = require("@loopstack/llm-provider-module");
+const oauth_module_1 = require("@loopstack/oauth-module");
+const authenticate_google_task_tool_1 = require("../../shared/google/authenticate-google-task.tool");
+let GoogleWorkspaceAgentExampleWorkflow = class GoogleWorkspaceAgentExampleWorkflow extends common_1.BaseWorkflow {
+    llmGenerateText;
+    llmDelegateToolCalls;
+    llmUpdateToolResult;
+    authenticateGoogle;
+    googleCalendarListCalendars;
+    googleCalendarFetchEvents;
+    googleCalendarCreateEvent;
+    gmailSearchMessages;
+    gmailGetMessage;
+    gmailSendMessage;
+    gmailReplyToMessage;
+    googleDriveListFiles;
+    googleDriveGetFileMetadata;
+    googleDriveDownloadFile;
+    googleDriveUploadFile;
+    oAuth;
+    constructor(llmGenerateText, llmDelegateToolCalls, llmUpdateToolResult, authenticateGoogle, googleCalendarListCalendars, googleCalendarFetchEvents, googleCalendarCreateEvent, gmailSearchMessages, gmailGetMessage, gmailSendMessage, gmailReplyToMessage, googleDriveListFiles, googleDriveGetFileMetadata, googleDriveDownloadFile, googleDriveUploadFile, oAuth) {
+        super();
+        this.llmGenerateText = llmGenerateText;
+        this.llmDelegateToolCalls = llmDelegateToolCalls;
+        this.llmUpdateToolResult = llmUpdateToolResult;
+        this.authenticateGoogle = authenticateGoogle;
+        this.googleCalendarListCalendars = googleCalendarListCalendars;
+        this.googleCalendarFetchEvents = googleCalendarFetchEvents;
+        this.googleCalendarCreateEvent = googleCalendarCreateEvent;
+        this.gmailSearchMessages = gmailSearchMessages;
+        this.gmailGetMessage = gmailGetMessage;
+        this.gmailSendMessage = gmailSendMessage;
+        this.gmailReplyToMessage = gmailReplyToMessage;
+        this.googleDriveListFiles = googleDriveListFiles;
+        this.googleDriveGetFileMetadata = googleDriveGetFileMetadata;
+        this.googleDriveDownloadFile = googleDriveDownloadFile;
+        this.googleDriveUploadFile = googleDriveUploadFile;
+        this.oAuth = oAuth;
+    }
+    async setup(_state) {
+        await this.documentStore.save(llm_provider_module_1.LlmContextDocument, {
+            role: 'user',
+            text: this.render((0, node_path_1.join)(__dirname, 'templates', 'systemMessage.md')),
+        });
+        await this.documentStore.save(llm_provider_module_1.LlmMessageDocument, {
+            role: 'assistant',
+            text: this.render((0, node_path_1.join)(__dirname, 'templates', 'welcomeMessage.md')),
+        });
+    }
+    async userMessage(_state, input) {
+        await this.documentStore.save(llm_provider_module_1.LlmMessageDocument, { role: 'user', text: input.data });
+    }
+    async llmTurn(_state) {
+        const result = await this.llmGenerateText.call({}, {
+            config: {
+                provider: 'claude',
+                model: 'claude-sonnet-4-6',
+                system: `You are a helpful Google Workspace assistant with access to Calendar, Gmail, and Drive tools.
+When a tool returns an unauthorized error, use authenticateGoogle to let the user sign in,
+then retry. Be concise and format results using markdown.`,
+                tools: [
+                    'google_calendar_list_calendars',
+                    'google_calendar_fetch_events',
+                    'google_calendar_create_event',
+                    'gmail_search_messages',
+                    'gmail_get_message',
+                    'gmail_send_message',
+                    'gmail_reply_to_message',
+                    'google_drive_list_files',
+                    'google_drive_get_file_metadata',
+                    'google_drive_download_file',
+                    'google_drive_upload_file',
+                    'authenticate_google',
+                ],
+            },
+        });
+        this.assignState({ llmResult: result.data });
+    }
+    async executeToolCalls(state) {
+        const result = await this.llmDelegateToolCalls.call({
+            message: state.llmResult.message,
+            callback: { transition: 'toolResultReceived' },
+        });
+        this.assignState({ delegateResult: result.data });
+    }
+    hasToolCalls(state) {
+        return state.llmResult?.message.stopReason === 'tool_use';
+    }
+    async toolResultReceived(state, input) {
+        const result = await this.llmUpdateToolResult.call({
+            delegateResult: state.delegateResult,
+            completedTool: input,
+        });
+        this.assignState({ delegateResult: result.data });
+    }
+    allToolsCompleteTransition(_state) { }
+    allToolsComplete(state) {
+        return state.delegateResult?.allCompleted ?? false;
+    }
+    respond(_state) { }
+};
+exports.GoogleWorkspaceAgentExampleWorkflow = GoogleWorkspaceAgentExampleWorkflow;
+__decorate([
+    (0, common_1.Transition)({ to: 'waiting_for_user' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], GoogleWorkspaceAgentExampleWorkflow.prototype, "setup", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'waiting_for_user', to: 'ready', wait: true, schema: zod_1.z.string() }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], GoogleWorkspaceAgentExampleWorkflow.prototype, "userMessage", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'ready', to: 'prompt_executed' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], GoogleWorkspaceAgentExampleWorkflow.prototype, "llmTurn", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'prompt_executed', to: 'awaiting_tools', priority: 10 }),
+    (0, common_1.Guard)('hasToolCalls'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], GoogleWorkspaceAgentExampleWorkflow.prototype, "executeToolCalls", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'awaiting_tools', to: 'awaiting_tools', wait: true, schema: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()) }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], GoogleWorkspaceAgentExampleWorkflow.prototype, "toolResultReceived", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'awaiting_tools', to: 'ready' }),
+    (0, common_1.Guard)('allToolsComplete'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], GoogleWorkspaceAgentExampleWorkflow.prototype, "allToolsCompleteTransition", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'prompt_executed', to: 'waiting_for_user' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], GoogleWorkspaceAgentExampleWorkflow.prototype, "respond", null);
+exports.GoogleWorkspaceAgentExampleWorkflow = GoogleWorkspaceAgentExampleWorkflow = __decorate([
+    (0, common_1.Workflow)({
+        title: 'OAuth - Google Workspace Agent Example',
+        description: 'An interactive chat agent with access to Google Calendar, Gmail, and Google Drive. Handles OAuth automatically — the agent detects unauthorized errors and launches authentication on its own.',
+        name: 'google_workspace_agent_example',
+        widget: './google-workspace-agent-example.ui.yaml',
+    }),
+    __metadata("design:paramtypes", [llm_provider_module_1.LlmGenerateTextTool,
+        llm_provider_module_1.LlmDelegateToolCallsTool,
+        llm_provider_module_1.LlmUpdateToolResultTool,
+        authenticate_google_task_tool_1.AuthenticateGoogleTask,
+        google_workspace_module_1.GoogleCalendarListCalendarsTool,
+        google_workspace_module_1.GoogleCalendarFetchEventsTool,
+        google_workspace_module_1.GoogleCalendarCreateEventTool,
+        google_workspace_module_1.GmailSearchMessagesTool,
+        google_workspace_module_1.GmailGetMessageTool,
+        google_workspace_module_1.GmailSendMessageTool,
+        google_workspace_module_1.GmailReplyToMessageTool,
+        google_workspace_module_1.GoogleDriveListFilesTool,
+        google_workspace_module_1.GoogleDriveGetFileMetadataTool,
+        google_workspace_module_1.GoogleDriveDownloadFileTool,
+        google_workspace_module_1.GoogleDriveUploadFileTool,
+        oauth_module_1.OAuthWorkflow])
+], GoogleWorkspaceAgentExampleWorkflow);
+//# sourceMappingURL=google-workspace-agent-example.workflow.js.map

package/dist/workflows/google-workspace-agent/google-workspace-agent-example.workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-workspace-agent-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/google-workspace-agent/google-workspace-agent-example.workflow.ts"],"names":[],"mappings":"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"}

package/dist/workflows/google-workspace-agent/templates/calendarSummary.md

@@ -0,0 +1,10 @@
+Here are your upcoming events:
+
+{{#each events}}
+
+- **{{ this.summary }}** — {{ this.start }} to {{ this.end }}
+  {{/each}}
+
+{{#unless events}}
+No upcoming events found.
+{{/unless}}

package/dist/workflows/google-workspace-agent/templates/systemMessage.md

@@ -0,0 +1,24 @@
+You are a helpful Google Workspace assistant. You have access to the user's
+Google Calendar, Gmail, and Google Drive through the tools provided to you.
+
+You can help with:
+
+- **Calendar**: List calendars, fetch events, create new events
+- **Gmail**: Search messages, read full emails, send new emails, reply to threads
+- **Drive**: Search files, get file details, download/export files, upload files
+
+When using date/time parameters, always use ISO 8601 format.
+
+When a tool returns `{ error: "unauthorized" }` or `{ error: "401" }`, call the
+`authenticateGoogle` tool with the required OAuth scopes to let the user sign in.
+After authentication completes, retry the original request.
+
+Common scopes:
+
+- Calendar: https://www.googleapis.com/auth/calendar.events
+- Gmail: https://www.googleapis.com/auth/gmail.modify
+- Drive: https://www.googleapis.com/auth/drive
+
+IMPORTANT: When using authenticateGoogle, it must be the ONLY tool call in your response.
+
+Be concise and helpful. Format results clearly using markdown.

package/dist/workflows/google-workspace-agent/templates/welcomeMessage.md

@@ -0,0 +1,7 @@
+Hi! I'm your Google Workspace assistant. I can help you with:
+
+- **Calendar** — list calendars, fetch events, create new events
+- **Gmail** — search messages, read details, send and reply to emails
+- **Drive** — browse files, view metadata, download and upload files
+
+I'll handle Google sign-in automatically when needed. What would you like to do?

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@loopstack/oauth-examples",
+  "displayName": "Loopstack OAuth Examples",
+  "description": "Workflow examples for OAuth-protected integrations in Loopstack — GitHub repos overview, GitHub agent, Google Calendar summary, Google Workspace agent.",
+  "keywords": [
+    "loopstack",
+    "example",
+    "oauth",
+    "github",
+    "google",
+    "workflow"
+  ],
+  "version": "0.1.1",
+  "license": "MIT",
+  "author": {
+    "name": "Jakob Klippel",
+    "url": "https://www.linkedin.com/in/jakob-klippel/"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./src/*": "./src/*"
+  },
+  "scripts": {
+    "build": "nest build",
+    "compile": "tsc --noEmit",
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "watch": "nest build --watch"
+  },
+  "dependencies": {
+    "@loopstack/claude-module": "*",
+    "@loopstack/common": "*",
+    "@loopstack/github-module": "*",
+    "@loopstack/google-workspace-module": "*",
+    "@loopstack/llm-provider-module": "*",
+    "@loopstack/oauth-module": "*",
+    "@nestjs/common": "^11.1.19",
+    "zod": "^4.3.6"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "vitest": "^4.1.6",
+    "@swc/core": "^1.15.33",
+    "unplugin-swc": "^1.5.9"
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './oauth-examples.module';
+export * from './workflows/github-overview/github-overview-example.workflow';
+export * from './workflows/github-agent/github-agent-example.workflow';
+export * from './workflows/google-calendar-summary/google-calendar-summary-example.workflow';
+export * from './workflows/google-workspace-agent/google-workspace-agent-example.workflow';
+export * from './shared/github';
+export * from './shared/google';

package/src/oauth-examples.module.ts

@@ -0,0 +1,30 @@
+import { Module } from '@nestjs/common';
+import { ClaudeModule } from '@loopstack/claude-module';
+import { StudioApp } from '@loopstack/common';
+import { GitHubModule } from '@loopstack/github-module';
+import { GoogleWorkspaceModule } from '@loopstack/google-workspace-module';
+import { AuthenticateGitHubTask } from './shared/github/authenticate-github-task.tool';
+import { AuthenticateGoogleTask } from './shared/google/authenticate-google-task.tool';
+import { GoogleCalendarFetchEventsTool } from './shared/google/google-calendar-fetch-events.tool';
+import { GithubAgentExampleWorkflow } from './workflows/github-agent/github-agent-example.workflow';
+import { GithubOverviewExampleWorkflow } from './workflows/github-overview/github-overview-example.workflow';
+import { GoogleCalendarSummaryExampleWorkflow } from './workflows/google-calendar-summary/google-calendar-summary-example.workflow';
+import { GoogleWorkspaceAgentExampleWorkflow } from './workflows/google-workspace-agent/google-workspace-agent-example.workflow';
+
+const WORKFLOWS = [
+  GithubOverviewExampleWorkflow,
+  GithubAgentExampleWorkflow,
+  GoogleCalendarSummaryExampleWorkflow,
+  GoogleWorkspaceAgentExampleWorkflow,
+];
+
+@StudioApp({
+  title: 'OAuth Examples',
+  workflows: WORKFLOWS,
+})
+@Module({
+  imports: [ClaudeModule, GitHubModule, GoogleWorkspaceModule],
+  providers: [AuthenticateGitHubTask, AuthenticateGoogleTask, GoogleCalendarFetchEventsTool, ...WORKFLOWS],
+  exports: [AuthenticateGitHubTask, AuthenticateGoogleTask, GoogleCalendarFetchEventsTool, ...WORKFLOWS],
+})
+export class OAuthExamplesModule {}

package/src/shared/github/authenticate-github-task.tool.ts

@@ -0,0 +1,70 @@
+import { Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { BaseTool, Tool, ToolCallOptions, ToolEnvelope } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import { OAuthWorkflow } from '@loopstack/oauth-module';
+
+const AuthenticateGitHubTaskInputSchema = z
+  .object({
+    scopes: z.array(z.string()).describe('The OAuth scopes to request (e.g. repo, user, workflow, read:org)'),
+    callback: z
+      .object({
+        transition: z.string(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+      })
+      .optional(),
+  })
+  .strict();
+
+type AuthenticateGitHubTaskInput = z.infer<typeof AuthenticateGitHubTaskInputSchema>;
+
+export type AuthenticateGitHubTaskResult = { workflowId: string; mode: string; [key: string]: unknown } | string;
+
+@Tool({
+  name: 'authenticate_github',
+  description:
+    'Launches GitHub OAuth authentication. Shows the user a sign-in prompt to authorize access to GitHub. ' +
+    'Use this when a GitHub tool returns an "unauthorized" error. ' +
+    'Pass the required OAuth scopes for the GitHub APIs you need access to. ' +
+    'IMPORTANT: When using this tool, it must be the ONLY tool call in your response. Do not combine it with other tool calls.',
+  schema: AuthenticateGitHubTaskInputSchema,
+})
+export class AuthenticateGitHubTask extends BaseTool<
+  AuthenticateGitHubTaskInput,
+  object,
+  AuthenticateGitHubTaskResult
+> {
+  private readonly logger = new Logger(AuthenticateGitHubTask.name);
+
+  constructor(private readonly oAuthWorkflow: OAuthWorkflow) {
+    super();
+  }
+
+  protected async handle(
+    args: AuthenticateGitHubTaskInput,
+    ctx: RunContext,
+    options?: ToolCallOptions,
+  ): Promise<ToolEnvelope<AuthenticateGitHubTaskResult>> {
+    const result = await this.oAuthWorkflow.run(
+      { provider: 'github', scopes: args.scopes },
+      { callback: options?.callback ?? args.callback, show: 'inline', label: 'GitHub authentication required' },
+    );
+
+    return {
+      data: { ...result, mode: 'async' },
+      pending: { workflowId: result.workflowId },
+    };
+  }
+
+  async complete(result: Record<string, unknown>): Promise<ToolEnvelope<AuthenticateGitHubTaskResult>> {
+    const status = result.status as string | undefined;
+    if (status === 'failed' || status === 'canceled') {
+      const detail = (result.errorMessage as string | undefined) ?? `Sub-workflow ${status}`;
+      const message = `GitHub authentication ${status}: ${detail}`;
+      return { data: message, error: message };
+    }
+    return {
+      data: 'GitHub authentication completed successfully. You can now use GitHub tools.',
+    };
+  }
+}

package/src/shared/github/index.ts

@@ -0,0 +1 @@
+export * from './authenticate-github-task.tool';

package/src/shared/google/authenticate-google-task.tool.ts

@@ -0,0 +1,72 @@
+import { Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { BaseTool, Tool, ToolCallOptions, ToolEnvelope } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import { OAuthWorkflow } from '@loopstack/oauth-module';
+
+const AuthenticateGoogleTaskInputSchema = z
+  .object({
+    scopes: z
+      .array(z.string())
+      .describe('The OAuth scopes to request (e.g. https://www.googleapis.com/auth/calendar.events)'),
+    callback: z
+      .object({
+        transition: z.string(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+      })
+      .optional(),
+  })
+  .strict();
+
+type AuthenticateGoogleTaskInput = z.infer<typeof AuthenticateGoogleTaskInputSchema>;
+
+export type AuthenticateGoogleTaskResult = { workflowId: string; mode: string; [key: string]: unknown } | string;
+
+@Tool({
+  name: 'authenticate_google',
+  description:
+    'Launches Google OAuth authentication. Shows the user a sign-in prompt to authorize access to Google services. ' +
+    'Use this when a Google tool returns an "unauthorized" error. ' +
+    'Pass the required OAuth scopes for the Google APIs you need access to. ' +
+    'IMPORTANT: When using this tool, it must be the ONLY tool call in your response. Do not combine it with other tool calls.',
+  schema: AuthenticateGoogleTaskInputSchema,
+})
+export class AuthenticateGoogleTask extends BaseTool<
+  AuthenticateGoogleTaskInput,
+  object,
+  AuthenticateGoogleTaskResult
+> {
+  private readonly logger = new Logger(AuthenticateGoogleTask.name);
+
+  constructor(private readonly oAuthWorkflow: OAuthWorkflow) {
+    super();
+  }
+
+  protected async handle(
+    args: AuthenticateGoogleTaskInput,
+    ctx: RunContext,
+    options?: ToolCallOptions,
+  ): Promise<ToolEnvelope<AuthenticateGoogleTaskResult>> {
+    const result = await this.oAuthWorkflow.run(
+      { provider: 'google', scopes: args.scopes },
+      { callback: options?.callback ?? args.callback, show: 'inline', label: 'Google authentication required' },
+    );
+
+    return {
+      data: { ...result, mode: 'async' },
+      pending: { workflowId: result.workflowId },
+    };
+  }
+
+  async complete(result: Record<string, unknown>): Promise<ToolEnvelope<AuthenticateGoogleTaskResult>> {
+    const status = result.status as string | undefined;
+    if (status === 'failed' || status === 'canceled') {
+      const detail = (result.errorMessage as string | undefined) ?? `Sub-workflow ${status}`;
+      const message = `Google authentication ${status}: ${detail}`;
+      return { data: message, error: message };
+    }
+    return {
+      data: 'Google authentication completed successfully. You can now use Google Workspace tools.',
+    };
+  }
+}

package/src/shared/google/google-calendar-fetch-events.tool.ts

@@ -0,0 +1,117 @@
+import { Logger } from '@nestjs/common';
+import { z } from 'zod';
+import { BaseTool, Tool, ToolEnvelope } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import { OAuthTokenStore } from '@loopstack/oauth-module';
+
+const GoogleCalendarFetchEventsSchema = z
+  .object({
+    timeMin: z.string(),
+    timeMax: z.string(),
+    calendarId: z.string().default('primary'),
+  })
+  .strict();
+
+type GoogleCalendarFetchEventsArgs = z.infer<typeof GoogleCalendarFetchEventsSchema>;
+
+export type GoogleCalendarFetchEventsResult = {
+  error?: string;
+  message?: string;
+  events?: { id: string; summary: string; start: string | undefined; end: string | undefined }[];
+};
+
+interface GoogleCalendarEvent {
+  id: string;
+  summary: string;
+  start: { dateTime?: string; date?: string };
+  end: { dateTime?: string; date?: string };
+}
+
+interface GoogleCalendarListResponse {
+  items: GoogleCalendarEvent[];
+}
+
+@Tool({
+  name: 'google_calendar_fetch_events',
+  description: 'Fetches events from Google Calendar. Returns { error: "unauthorized" } if no valid token is available.',
+  schema: GoogleCalendarFetchEventsSchema,
+})
+export class GoogleCalendarFetchEventsTool extends BaseTool<
+  GoogleCalendarFetchEventsArgs,
+  object,
+  GoogleCalendarFetchEventsResult
+> {
+  private readonly logger = new Logger(GoogleCalendarFetchEventsTool.name);
+
+  constructor(private readonly tokenStore: OAuthTokenStore) {
+    super();
+  }
+
+  protected async handle(
+    args: GoogleCalendarFetchEventsArgs,
+    ctx: RunContext,
+  ): Promise<ToolEnvelope<GoogleCalendarFetchEventsResult>> {
+    const accessToken = await this.tokenStore.getValidAccessToken(ctx.userId, 'google');
+
+    if (!accessToken) {
+      return {
+        data: {
+          error: 'unauthorized',
+          message: 'No valid Google token found. Please authenticate first.',
+        },
+        error: 'No valid Google token found. Please authenticate first.',
+      };
+    }
+
+    const calendarId = args.calendarId || 'primary';
+    const params = new URLSearchParams({
+      timeMin: args.timeMin,
+      timeMax: args.timeMax,
+      singleEvents: 'true',
+      orderBy: 'startTime',
+    });
+
+    const response = await fetch(
+      `https://www.googleapis.com/calendar/v3/calendars/${encodeURIComponent(calendarId)}/events?${params.toString()}`,
+      {
+        headers: { Authorization: `Bearer ${accessToken}` },
+      },
+    );
+
+    if (response.status === 401 || response.status === 403) {
+      this.logger.warn(`Google Calendar API returned ${response.status} for user ${ctx.userId}`);
+      return {
+        data: {
+          error: '401',
+          message: 'Google token was rejected. Please re-authenticate.',
+        },
+        error: 'Google token was rejected. Please re-authenticate.',
+      };
+    }
+
+    if (!response.ok) {
+      const body = await response.text();
+      this.logger.error(`Google Calendar API error: ${response.status} ${body}`);
+      console.log('api_error', response.statusText);
+      return {
+        data: {
+          error: 'api_error',
+          message: `Google Calendar API error: ${response.statusText}`,
+        },
+        error: `Google Calendar API error: ${response.statusText}`,
+      };
+    }
+
+    const data: GoogleCalendarListResponse = (await response.json()) as GoogleCalendarListResponse;
+    const events = data.items.map((event) => ({
+      id: event.id,
+      summary: event.summary,
+      start: event.start.dateTime || event.start.date,
+      end: event.end.dateTime || event.end.date,
+    }));
+
+    return {
+      data: { events },
+    };
+  }
+}

package/src/shared/google/index.ts

@@ -0,0 +1,2 @@
+export * from './authenticate-google-task.tool';
+export * from './google-calendar-fetch-events.tool';

package/src/workflows/github-agent/github-agent-example.ui.yaml

@@ -0,0 +1,6 @@
+widget: prompt-input
+enabledWhen:
+  - waiting_for_user
+options:
+  transition: userMessage
+  label: Send Message