@loopstack/oauth-examples 0.1.1

package/src/workflows/github-agent/github-agent-example.workflow.ts

@@ -0,0 +1,193 @@
+import { join } from 'node:path';
+import { z } from 'zod';
+import { BaseWorkflow, Guard, Transition, Workflow } from '@loopstack/common';
+import type { TransitionInput } from '@loopstack/common';
+import {
+  GitHubCreateIssueCommentTool,
+  GitHubCreateIssueTool,
+  GitHubCreateOrUpdateFileTool,
+  GitHubCreatePullRequestTool,
+  GitHubCreateRepoTool,
+  GitHubGetAuthenticatedUserTool,
+  GitHubGetCommitTool,
+  GitHubGetFileContentTool,
+  GitHubGetIssueTool,
+  GitHubGetPullRequestTool,
+  GitHubGetRepoTool,
+  GitHubGetWorkflowRunTool,
+  GitHubListBranchesTool,
+  GitHubListDirectoryTool,
+  GitHubListIssuesTool,
+  GitHubListPrReviewsTool,
+  GitHubListPullRequestsTool,
+  GitHubListReposTool,
+  GitHubListUserOrgsTool,
+  GitHubListWorkflowRunsTool,
+  GitHubMergePullRequestTool,
+  GitHubSearchCodeTool,
+  GitHubSearchIssuesTool,
+  GitHubSearchReposTool,
+  GitHubTriggerWorkflowTool,
+} from '@loopstack/github-module';
+import type { LlmDelegateResult, LlmGenerateTextResult } from '@loopstack/llm-provider-module';
+import {
+  LlmContextDocument,
+  LlmDelegateToolCallsTool,
+  LlmGenerateTextTool,
+  LlmMessageDocument,
+  LlmUpdateToolResultTool,
+} from '@loopstack/llm-provider-module';
+import { OAuthWorkflow } from '@loopstack/oauth-module';
+import { AuthenticateGitHubTask } from '../../shared/github/authenticate-github-task.tool';
+
+interface GitHubAgentState {
+  llmResult?: LlmGenerateTextResult;
+  delegateResult?: LlmDelegateResult;
+}
+
+@Workflow({
+  title: 'OAuth - GitHub Agent Example',
+  description:
+    'An interactive chat agent with access to GitHub. Manages repositories, issues, pull requests, code, CI/CD, and search. Handles OAuth authentication automatically — the agent detects unauthorized errors and launches authentication on its own.',
+  name: 'github_agent_example',
+  widget: './github-agent-example.ui.yaml',
+})
+export class GithubAgentExampleWorkflow extends BaseWorkflow {
+  constructor(
+    private readonly llmGenerateText: LlmGenerateTextTool,
+    private readonly llmDelegateToolCalls: LlmDelegateToolCallsTool,
+    private readonly llmUpdateToolResult: LlmUpdateToolResultTool,
+    private readonly authenticateGitHub: AuthenticateGitHubTask,
+    // GitHub Repos tools
+    private readonly gitHubListRepos: GitHubListReposTool,
+    private readonly gitHubGetRepo: GitHubGetRepoTool,
+    private readonly gitHubCreateRepo: GitHubCreateRepoTool,
+    private readonly gitHubListBranches: GitHubListBranchesTool,
+    // GitHub Issues tools
+    private readonly gitHubListIssues: GitHubListIssuesTool,
+    private readonly gitHubGetIssue: GitHubGetIssueTool,
+    private readonly gitHubCreateIssue: GitHubCreateIssueTool,
+    private readonly gitHubCreateIssueComment: GitHubCreateIssueCommentTool,
+    // GitHub Pull Requests tools
+    private readonly gitHubListPullRequests: GitHubListPullRequestsTool,
+    private readonly gitHubGetPullRequest: GitHubGetPullRequestTool,
+    private readonly gitHubCreatePullRequest: GitHubCreatePullRequestTool,
+    private readonly gitHubMergePullRequest: GitHubMergePullRequestTool,
+    private readonly gitHubListPrReviews: GitHubListPrReviewsTool,
+    // GitHub Content / Git Ops tools
+    private readonly gitHubGetFileContent: GitHubGetFileContentTool,
+    private readonly gitHubCreateOrUpdateFile: GitHubCreateOrUpdateFileTool,
+    private readonly gitHubListDirectory: GitHubListDirectoryTool,
+    private readonly gitHubGetCommit: GitHubGetCommitTool,
+    // GitHub Actions tools
+    private readonly gitHubListWorkflowRuns: GitHubListWorkflowRunsTool,
+    private readonly gitHubTriggerWorkflow: GitHubTriggerWorkflowTool,
+    private readonly gitHubGetWorkflowRun: GitHubGetWorkflowRunTool,
+    // GitHub Search tools
+    private readonly gitHubSearchCode: GitHubSearchCodeTool,
+    private readonly gitHubSearchRepos: GitHubSearchReposTool,
+    private readonly gitHubSearchIssues: GitHubSearchIssuesTool,
+    // GitHub Users & Orgs tools
+    private readonly gitHubGetAuthenticatedUser: GitHubGetAuthenticatedUserTool,
+    private readonly gitHubListUserOrgs: GitHubListUserOrgsTool,
+    private readonly oAuth: OAuthWorkflow,
+  ) {
+    super();
+  }
+
+  @Transition({ to: 'waiting_for_user' })
+  async setup(_state: GitHubAgentState) {
+    await this.documentStore.save(LlmContextDocument, {
+      role: 'user',
+      text: this.render(join(__dirname, 'templates', 'systemMessage.md')),
+    });
+    await this.documentStore.save(LlmMessageDocument, {
+      role: 'assistant',
+      text: this.render(join(__dirname, 'templates', 'welcomeMessage.md')),
+    });
+  }
+
+  @Transition({ from: 'waiting_for_user', to: 'ready', wait: true, schema: z.string() })
+  async userMessage(_state: GitHubAgentState, input: TransitionInput<string>) {
+    await this.documentStore.save(LlmMessageDocument, { role: 'user', text: input.data });
+  }
+
+  @Transition({ from: 'ready', to: 'prompt_executed' })
+  async llmTurn(_state: GitHubAgentState) {
+    const result = await this.llmGenerateText.call(
+      {},
+      {
+        config: {
+          provider: 'claude',
+          model: 'claude-sonnet-4-6',
+          system: `You are a helpful GitHub assistant with access to repository, issue, PR, code, actions,
+and search tools. When a tool returns an unauthorized error, use authenticateGitHub
+to let the user sign in, then retry. Be concise and format results using markdown.`,
+          tools: [
+            'github_list_repos',
+            'github_get_repo',
+            'github_create_repo',
+            'github_list_branches',
+            'github_list_issues',
+            'github_get_issue',
+            'github_create_issue',
+            'github_create_issue_comment',
+            'github_list_pull_requests',
+            'github_get_pull_request',
+            'github_create_pull_request',
+            'github_merge_pull_request',
+            'github_list_pr_reviews',
+            'github_get_file_content',
+            'github_create_or_update_file',
+            'github_list_directory',
+            'github_get_commit',
+            'github_list_workflow_runs',
+            'github_trigger_workflow',
+            'github_get_workflow_run',
+            'github_search_code',
+            'github_search_repos',
+            'github_search_issues',
+            'github_get_authenticated_user',
+            'github_list_user_orgs',
+            'authenticate_github',
+          ],
+        },
+      },
+    );
+    this.assignState({ llmResult: result.data });
+  }
+
+  @Transition({ from: 'prompt_executed', to: 'awaiting_tools', priority: 10 })
+  @Guard('hasToolCalls')
+  async executeToolCalls(state: GitHubAgentState) {
+    const result = await this.llmDelegateToolCalls.call({
+      message: state.llmResult!.message,
+      callback: { transition: 'toolResultReceived' },
+    });
+    this.assignState({ delegateResult: result.data });
+  }
+
+  hasToolCalls(state: GitHubAgentState): boolean {
+    return state.llmResult?.message.stopReason === 'tool_use';
+  }
+
+  @Transition({ from: 'awaiting_tools', to: 'awaiting_tools', wait: true, schema: z.record(z.string(), z.unknown()) })
+  async toolResultReceived(state: GitHubAgentState, input: TransitionInput<Record<string, unknown>>) {
+    const result = await this.llmUpdateToolResult.call({
+      delegateResult: state.delegateResult!,
+      completedTool: input,
+    });
+    this.assignState({ delegateResult: result.data });
+  }
+
+  @Transition({ from: 'awaiting_tools', to: 'ready' })
+  @Guard('allToolsComplete')
+  allToolsCompleteTransition(_state: GitHubAgentState) {}
+
+  allToolsComplete(state: GitHubAgentState): boolean {
+    return state.delegateResult?.allCompleted ?? false;
+  }
+
+  @Transition({ from: 'prompt_executed', to: 'waiting_for_user' })
+  respond(_state: GitHubAgentState) {}
+}

package/src/workflows/github-agent/templates/systemMessage.md

@@ -0,0 +1,23 @@
+You are a helpful GitHub assistant. You have access to the user's
+GitHub account through the tools provided to you.
+
+You can help with:
+
+- **Repositories**: List repos, get repo details, create repos, list branches
+- **Issues**: List issues, get issue details, create issues, comment on issues
+- **Pull Requests**: List PRs, get PR details, create PRs, merge PRs, list reviews
+- **Code & Content**: Read files, create/update files, browse directories, view commits
+- **Actions (CI/CD)**: List workflow runs, trigger workflows, check run status
+- **Search**: Search code, repositories, and issues across GitHub
+- **Users & Orgs**: Get user profile, list organizations
+
+When a tool returns `{ error: "unauthorized" }` or `{ error: "401" }`, call the
+`authenticateGitHub` tool with the required OAuth scopes to let the user sign in.
+After authentication completes, retry the original request.
+
+Common scopes: repo, user, workflow, read:org
+
+IMPORTANT: When using authenticateGitHub, it must be the ONLY tool call in your response.
+
+Be concise and helpful. Format results clearly using markdown.
+When showing repository or issue information, include links where available.

package/src/workflows/github-agent/templates/welcomeMessage.md

@@ -0,0 +1,10 @@
+Hi! I'm your GitHub assistant. I can help you with:
+
+- **Repositories** — list, create, view branches and details
+- **Issues** — list, create, comment, view details
+- **Pull Requests** — list, create, merge, review
+- **Code & Content** — read files, browse directories, view commits
+- **Actions (CI/CD)** — list runs, trigger workflows, check status
+- **Search** — search code, repositories, and issues across GitHub
+
+I'll handle GitHub sign-in automatically when needed. What would you like to do?

package/src/workflows/github-overview/github-overview-example.workflow.ts

@@ -0,0 +1,223 @@
+import { join } from 'node:path';
+import { z } from 'zod';
+import { BaseWorkflow, Guard, MarkdownDocument, Transition, Workflow } from '@loopstack/common';
+import type { RunContext, TransitionInput } from '@loopstack/common';
+import {
+  GitHubGetAuthenticatedUserTool,
+  GitHubGetRepoTool,
+  GitHubListBranchesTool,
+  GitHubListDirectoryTool,
+  GitHubListIssuesTool,
+  GitHubListPullRequestsTool,
+  GitHubListUserOrgsTool,
+  GitHubListWorkflowRunsTool,
+  GitHubSearchCodeTool,
+} from '@loopstack/github-module';
+import { OAuthWorkflow } from '@loopstack/oauth-module';
+
+interface GitHubReposOverviewState {
+  owner: string;
+  repo: string;
+  requiresAuthentication?: boolean;
+  user?: { login: string; name: string | null; htmlUrl: string; publicRepos: number };
+  orgs?: Array<{ login: string; description: string | null }>;
+  repoDetails?: {
+    fullName: string;
+    description: string | null;
+    language: string | null;
+    stars: number;
+    forks: number;
+    openIssues: number;
+    defaultBranch: string;
+    htmlUrl: string;
+  };
+  branches?: Array<{ name: string; protected: boolean }>;
+  issues?: Array<{ number: number; title: string; state: string; user: string; htmlUrl: string }>;
+  pullRequests?: Array<{
+    number: number;
+    title: string;
+    state: string;
+    user: string;
+    draft: boolean;
+    htmlUrl: string;
+  }>;
+  directoryEntries?: Array<{ name: string; type: string; path: string }>;
+  workflowRuns?: Array<{
+    id: number;
+    name: string;
+    status: string;
+    conclusion: string | null;
+    htmlUrl: string;
+  }>;
+  searchResults?: Array<{ name: string; path: string; repository: string }>;
+}
+
+const GitHubReposOverviewArgsSchema = z
+  .object({
+    owner: z.string().default('octocat'),
+    repo: z.string().default('Hello-World'),
+  })
+  .strict();
+
+type GitHubReposOverviewArgs = z.infer<typeof GitHubReposOverviewArgsSchema>;
+
+@Workflow({
+  title: 'OAuth - GitHub Overview Example',
+  description:
+    'Comprehensive GitHub example that exercises every GitHub tool. Fetches user info, repository details, issues, pull requests, branches, directory contents, workflow runs, and search results. Launches the OAuth sub-workflow on unauthorized errors and retries.',
+  name: 'github_overview_example',
+  schema: GitHubReposOverviewArgsSchema,
+})
+export class GithubOverviewExampleWorkflow extends BaseWorkflow<GitHubReposOverviewArgs> {
+  constructor(
+    private readonly gitHubGetAuthenticatedUser: GitHubGetAuthenticatedUserTool,
+    private readonly gitHubListUserOrgs: GitHubListUserOrgsTool,
+    private readonly gitHubGetRepo: GitHubGetRepoTool,
+    private readonly gitHubListBranches: GitHubListBranchesTool,
+    private readonly gitHubListIssues: GitHubListIssuesTool,
+    private readonly gitHubListPullRequests: GitHubListPullRequestsTool,
+    private readonly gitHubListDirectory: GitHubListDirectoryTool,
+    private readonly gitHubListWorkflowRuns: GitHubListWorkflowRunsTool,
+    private readonly gitHubSearchCode: GitHubSearchCodeTool,
+    private readonly oAuthWorkflow: OAuthWorkflow,
+  ) {
+    super();
+  }
+
+  // --- Step 1: Fetch authenticated user ---
+
+  @Transition({ to: 'user_fetched' })
+  async fetchUser(state: GitHubReposOverviewState, ctx: RunContext<GitHubReposOverviewArgs>) {
+    try {
+      const result = await this.gitHubGetAuthenticatedUser.call();
+      this.assignState({
+        owner: ctx.args.owner,
+        repo: ctx.args.repo,
+        requiresAuthentication: false,
+        user: result.data.user,
+      });
+    } catch (error) {
+      // GitHub tools throw with a human-readable message on auth failure
+      // ("No valid GitHub token found. Please authenticate first." / "GitHub token was rejected. Please re-authenticate.").
+      // Match on "authenticate" to route through the OAuth sub-workflow; rethrow everything else.
+      if (error instanceof Error && /authenticate/i.test(error.message)) {
+        this.assignState({ owner: ctx.args.owner, repo: ctx.args.repo, requiresAuthentication: true });
+        return;
+      }
+      throw error;
+    }
+  }
+
+  // If unauthorized -> launch OAuth
+  @Transition({ from: 'user_fetched', to: 'awaiting_auth', priority: 10 })
+  @Guard('needsAuth')
+  async authRequired(_state: GitHubReposOverviewState) {
+    await this.oAuthWorkflow.run(
+      { provider: 'github', scopes: ['repo', 'read:org', 'workflow'] },
+      { callback: { transition: 'authCompleted' }, show: 'inline', label: 'GitHub authentication required' },
+    );
+  }
+
+  needsAuth(state: GitHubReposOverviewState): boolean {
+    return !!state.requiresAuthentication;
+  }
+
+  // Auth completed -> retry from start
+  @Transition({
+    from: 'awaiting_auth',
+    to: 'start',
+    wait: true,
+  })
+  authCompleted(_state: GitHubReposOverviewState, _input: TransitionInput) {}
+
+  // --- Step 2: Fetch user orgs ---
+
+  @Transition({ from: 'user_fetched', to: 'orgs_fetched' })
+  async fetchOrgs(_state: GitHubReposOverviewState) {
+    const result = await this.gitHubListUserOrgs.call({ perPage: 10 });
+    this.assignState({ orgs: result.data.orgs });
+  }
+
+  // --- Step 3: Fetch repo details and branches ---
+
+  @Transition({ from: 'orgs_fetched', to: 'repo_fetched' })
+  async fetchRepoDetails(state: GitHubReposOverviewState) {
+    const repoResult = await this.gitHubGetRepo.call({
+      owner: state.owner,
+      repo: state.repo,
+    });
+
+    const branchesResult = await this.gitHubListBranches.call({
+      owner: state.owner,
+      repo: state.repo,
+    });
+    this.assignState({ repoDetails: repoResult.data.repo, branches: branchesResult.data.branches });
+  }
+
+  // --- Step 4: Fetch issues and PRs ---
+
+  @Transition({ from: 'repo_fetched', to: 'issues_prs_fetched' })
+  async fetchIssuesPrs(state: GitHubReposOverviewState) {
+    const issuesResult = await this.gitHubListIssues.call({
+      owner: state.owner,
+      repo: state.repo,
+      state: 'open',
+      perPage: 10,
+    });
+
+    const prsResult = await this.gitHubListPullRequests.call({
+      owner: state.owner,
+      repo: state.repo,
+      state: 'open',
+      perPage: 10,
+    });
+    this.assignState({ issues: issuesResult.data.issues, pullRequests: prsResult.data.pullRequests });
+  }
+
+  // --- Step 5: Fetch directory listing and workflow runs ---
+
+  @Transition({ from: 'issues_prs_fetched', to: 'content_actions_fetched' })
+  async fetchContentActions(state: GitHubReposOverviewState) {
+    const dirResult = await this.gitHubListDirectory.call({
+      owner: state.owner,
+      repo: state.repo,
+    });
+
+    const runsResult = await this.gitHubListWorkflowRuns.call({
+      owner: state.owner,
+      repo: state.repo,
+      perPage: 5,
+    });
+    this.assignState({ directoryEntries: dirResult.data.entries, workflowRuns: runsResult.data.runs });
+  }
+
+  // --- Step 6: Search code in the repo ---
+
+  @Transition({ from: 'content_actions_fetched', to: 'search_done' })
+  async fetchSearch(state: GitHubReposOverviewState) {
+    const result = await this.gitHubSearchCode.call({
+      query: `repo:${state.owner}/${state.repo}`,
+      perPage: 5,
+    });
+    this.assignState({ searchResults: result.data.results });
+  }
+
+  // --- Display all results ---
+
+  @Transition({ from: 'search_done', to: 'end' })
+  async displayResults(state: GitHubReposOverviewState) {
+    await this.documentStore.save(MarkdownDocument, {
+      markdown: this.render(join(__dirname, 'templates', 'repoOverview.md'), {
+        user: state.user,
+        orgs: state.orgs,
+        repo: state.repoDetails,
+        branches: state.branches,
+        issues: state.issues,
+        pullRequests: state.pullRequests,
+        directoryEntries: state.directoryEntries,
+        workflowRuns: state.workflowRuns,
+        searchResults: state.searchResults,
+      }),
+    });
+  }
+}

package/src/workflows/github-overview/templates/repoOverview.md

@@ -0,0 +1,81 @@
+## Authenticated User
+
+**{{ user.login }}** {{#if user.name}}({{ user.name }}){{/if}} — {{ user.publicRepos }} public repos
+
+{{#if orgs}}
+
+### Organizations
+
+{{#each orgs}}
+
+- **{{ this.login }}** {{#if this.description}}— {{ this.description }}{{/if}}
+  {{/each}}
+  {{/if}}
+
+---
+
+## Repository: [{{ repo.fullName }}]({{ repo.htmlUrl }})
+
+{{ repo.description }}
+
+| Language            | Stars            | Forks            | Open Issues           | Default Branch           |
+| ------------------- | ---------------- | ---------------- | --------------------- | ------------------------ |
+| {{ repo.language }} | {{ repo.stars }} | {{ repo.forks }} | {{ repo.openIssues }} | {{ repo.defaultBranch }} |
+
+### Branches
+
+{{#each branches}}
+
+- `{{ this.name }}` {{#if this.protected}}(protected){{/if}}
+  {{/each}}
+
+---
+
+### Open Issues
+
+{{#each issues}}
+
+- [#{{ this.number }}]({{ this.htmlUrl }}) {{ this.title }} — @{{ this.user }}
+  {{/each}}
+  {{#unless issues}}
+  No open issues.
+  {{/unless}}
+
+### Open Pull Requests
+
+{{#each pullRequests}}
+
+- [#{{ this.number }}]({{ this.htmlUrl }}) {{ this.title }} — @{{ this.user }} {{#if this.draft}}(draft){{/if}}
+  {{/each}}
+  {{#unless pullRequests}}
+  No open pull requests.
+  {{/unless}}
+
+---
+
+### Root Directory
+
+{{#each directoryEntries}}
+
+- {{ this.type }} `{{ this.name }}`
+  {{/each}}
+
+### Recent Workflow Runs
+
+{{#each workflowRuns}}
+
+- [{{ this.name }}]({{ this.htmlUrl }}) — {{ this.status }} {{#if this.conclusion}}({{ this.conclusion }}){{/if}}
+  {{/each}}
+  {{#unless workflowRuns}}
+  No workflow runs found.
+  {{/unless}}
+
+### Code Search Results
+
+{{#each searchResults}}
+
+- `{{ this.path }}` in {{ this.repository }}
+  {{/each}}
+  {{#unless searchResults}}
+  No code search results.
+  {{/unless}}

package/src/workflows/google-calendar-summary/google-calendar-summary-example.workflow.ts

@@ -0,0 +1,102 @@
+import { join } from 'node:path';
+import { z } from 'zod';
+import { BaseWorkflow, Guard, MarkdownDocument, Transition, Workflow } from '@loopstack/common';
+import type { RunContext, TransitionInput } from '@loopstack/common';
+import { OAuthWorkflow } from '@loopstack/oauth-module';
+import { GoogleCalendarFetchEventsTool } from '../../shared/google';
+
+interface CalendarSummaryState {
+  events?: Array<{ id: string; summary: string; start?: string; end?: string }>;
+  requiresAuthentication?: boolean;
+}
+
+const CalendarSummaryArgsSchema = z
+  .object({
+    calendarId: z.string().default('primary'),
+  })
+  .strict();
+
+type CalendarSummaryArgs = z.infer<typeof CalendarSummaryArgsSchema>;
+
+@Workflow({
+  title: 'OAuth - Google Calendar Summary Example',
+  description:
+    'Fetches upcoming Google Calendar events and displays a summary. Launches the OAuth workflow as a sub-workflow on unauthorized errors and retries automatically.',
+  name: 'google_calendar_summary_example',
+  schema: CalendarSummaryArgsSchema,
+})
+export class GoogleCalendarSummaryExampleWorkflow extends BaseWorkflow<CalendarSummaryArgs> {
+  constructor(
+    private readonly googleCalendarFetchEvents: GoogleCalendarFetchEventsTool,
+    private readonly oAuthWorkflow: OAuthWorkflow,
+  ) {
+    super();
+  }
+
+  // --- Fetch events from Google Calendar ---
+
+  @Transition({ to: 'calendar_fetched' })
+  async fetchEvents(state: CalendarSummaryState, ctx: RunContext<CalendarSummaryArgs>) {
+    try {
+      const result = await this.googleCalendarFetchEvents.call({
+        calendarId: ctx.args.calendarId,
+        timeMin: this.now(),
+        timeMax: this.endOfWeek(),
+      });
+      this.assignState({ requiresAuthentication: false, events: result.data.events });
+    } catch (error) {
+      // The Google tools throw with their human-readable message on auth failure
+      // ("No valid Google token found. Please authenticate first." / "Google token was rejected. Please re-authenticate.").
+      // Both contain "authenticate" — match on that to route through the OAuth sub-workflow.
+      if (error instanceof Error && /authenticate/i.test(error.message)) {
+        this.assignState({ requiresAuthentication: true });
+        return;
+      }
+      throw error;
+    }
+  }
+
+  // If unauthorized -> launch OAuth as sub-workflow
+  @Transition({ from: 'calendar_fetched', to: 'awaiting_auth', priority: 10 })
+  @Guard('needsAuth')
+  async authRequired(_state: CalendarSummaryState) {
+    await this.oAuthWorkflow.run(
+      { provider: 'google', scopes: ['https://www.googleapis.com/auth/calendar.readonly'] },
+      { callback: { transition: 'authCompleted' }, show: 'inline', label: 'Google authentication required' },
+    );
+  }
+
+  needsAuth(state: CalendarSummaryState): boolean {
+    return !!state.requiresAuthentication;
+  }
+
+  // Auth sub-workflow completed -> retry from start
+  @Transition({
+    from: 'awaiting_auth',
+    to: 'start',
+    wait: true,
+  })
+  authCompleted(_state: CalendarSummaryState, _input: TransitionInput) {}
+
+  // Success -> display summary
+  @Transition({ from: 'calendar_fetched', to: 'end' })
+  async displayResults(state: CalendarSummaryState) {
+    await this.documentStore.save(MarkdownDocument, {
+      markdown: this.render(join(__dirname, 'templates', 'calendarSummary.md'), { events: state.events }),
+    });
+  }
+
+  private now(): string {
+    return new Date().toISOString();
+  }
+
+  private endOfWeek(): string {
+    const now = new Date();
+    const dayOfWeek = now.getDay();
+    const daysUntilSunday = dayOfWeek === 0 ? 7 : 7 - dayOfWeek;
+    const endOfWeek = new Date(now);
+    endOfWeek.setDate(now.getDate() + daysUntilSunday);
+    endOfWeek.setHours(23, 59, 59, 999);
+    return endOfWeek.toISOString();
+  }
+}

package/src/workflows/google-calendar-summary/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/src/workflows/google-workspace-agent/google-workspace-agent-example.ui.yaml

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