@loopstack/github-oauth-example 0.3.0 → 0.4.0

package/src/workflows/__tests__/github-repos-overview-workflow.spec.ts

@@ -1,7 +1,7 @@
 import { TestingModule } from '@nestjs/testing';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { z } from 'zod';
-import { RunContext, WorkflowEntity, getBlockArgsSchema, getBlockConfig, getBlockTools } from '@loopstack/common';
+import { RunContext, WorkflowEntity, getBlockArgsSchema, getBlockConfig } from '@loopstack/common';
 import { WorkflowProcessorService } from '@loopstack/core';
 import {
   GitHubCreateIssueCommentTool,
@@ -35,7 +35,7 @@ import { ToolMock, createStatelessContext, createWorkflowTest } from '@loopstack
 import { GitHubReposOverviewWorkflow } from '../github-repos-overview.workflow';
 
 const mockOAuthWorkflow = {
-  run: vi.fn(),
+  run: vi.fn().mockResolvedValue({ workflowId: 'sub-1' }),
 };
 
 function applyAllGitHubToolMocks(builder: ReturnType<typeof createWorkflowTest>) {
@@ -72,7 +72,7 @@ function buildWorkflowTest() {
     createWorkflowTest()
       .forWorkflow(GitHubReposOverviewWorkflow)
       .withImports(OAuthModule)
-      .withMock(OAuthWorkflow, mockOAuthWorkflow),
+      .withOverride(OAuthWorkflow, mockOAuthWorkflow),
   );
 }
 
@@ -130,20 +130,16 @@ describe('GitHubReposOverviewWorkflow', () => {
       expect(getBlockConfig(workflow)).toBeDefined();
     });
 
-    it('should have GitHub tools available', () => {
-      const tools = getBlockTools(workflow);
-      expect(tools).toBeDefined();
-
-      expect(tools).toContain('gitHubGetAuthenticatedUser');
-      expect(tools).toContain('gitHubListUserOrgs');
-      expect(tools).toContain('gitHubGetRepo');
-
-      expect(tools).toContain('gitHubListBranches');
-      expect(tools).toContain('gitHubListIssues');
-      expect(tools).toContain('gitHubListPullRequests');
-      expect(tools).toContain('gitHubListDirectory');
-      expect(tools).toContain('gitHubListWorkflowRuns');
-      expect(tools).toContain('gitHubSearchCode');
+    it('should have GitHub tools available via constructor injection', () => {
+      expect(mockGetAuthenticatedUser).toBeDefined();
+      expect(mockListUserOrgs).toBeDefined();
+      expect(mockGetRepo).toBeDefined();
+      expect(mockListBranches).toBeDefined();
+      expect(mockListIssues).toBeDefined();
+      expect(mockListPullRequests).toBeDefined();
+      expect(mockListDirectory).toBeDefined();
+      expect(mockListWorkflowRuns).toBeDefined();
+      expect(mockSearchCode).toBeDefined();
     });
   });
 
@@ -330,9 +326,7 @@ describe('GitHubReposOverviewWorkflow', () => {
       expect(result.place).toBe('end');
 
       // Verify markdown document was created
-      expect(result.documents).toEqual(
-        expect.arrayContaining([expect.objectContaining({ className: 'MarkdownDocument' })]),
-      );
+      expect(result.documents).toEqual(expect.arrayContaining([expect.objectContaining({ documentName: 'markdown' })]));
 
       // Verify all read tools were called
       expect(mockGetAuthenticatedUser.call).toHaveBeenCalledTimes(1);
@@ -352,10 +346,7 @@ describe('GitHubReposOverviewWorkflow', () => {
 
       await processor.process(workflow, args, context);
 
-      expect(mockGetRepo.call).toHaveBeenCalledWith(
-        expect.objectContaining({ owner: 'octocat', repo: 'Hello-World' }),
-        undefined,
-      );
+      expect(mockGetRepo.call).toHaveBeenCalledWith(expect.objectContaining({ owner: 'octocat', repo: 'Hello-World' }));
     });
 
     it('should pass owner and repo to gitHubListBranches', async () => {
@@ -366,7 +357,6 @@ describe('GitHubReposOverviewWorkflow', () => {
 
       expect(mockListBranches.call).toHaveBeenCalledWith(
         expect.objectContaining({ owner: 'octocat', repo: 'Hello-World' }),
-        undefined,
       );
     });
 
@@ -378,7 +368,6 @@ describe('GitHubReposOverviewWorkflow', () => {
 
       expect(mockListIssues.call).toHaveBeenCalledWith(
         expect.objectContaining({ owner: 'octocat', repo: 'Hello-World', state: 'open' }),
-        undefined,
       );
     });
 
@@ -390,7 +379,6 @@ describe('GitHubReposOverviewWorkflow', () => {
 
       expect(mockListPullRequests.call).toHaveBeenCalledWith(
         expect.objectContaining({ owner: 'octocat', repo: 'Hello-World', state: 'open' }),
-        undefined,
       );
     });
 
@@ -402,7 +390,6 @@ describe('GitHubReposOverviewWorkflow', () => {
 
       expect(mockListDirectory.call).toHaveBeenCalledWith(
         expect.objectContaining({ owner: 'octocat', repo: 'Hello-World' }),
-        undefined,
       );
     });
 
@@ -414,7 +401,6 @@ describe('GitHubReposOverviewWorkflow', () => {
 
       expect(mockListWorkflowRuns.call).toHaveBeenCalledWith(
         expect.objectContaining({ owner: 'octocat', repo: 'Hello-World' }),
-        undefined,
       );
     });
 
@@ -424,10 +410,7 @@ describe('GitHubReposOverviewWorkflow', () => {
 
       await processor.process(workflow, args, context);
 
-      expect(mockSearchCode.call).toHaveBeenCalledWith(
-        expect.objectContaining({ query: 'repo:octocat/Hello-World' }),
-        undefined,
-      );
+      expect(mockSearchCode.call).toHaveBeenCalledWith(expect.objectContaining({ query: 'repo:octocat/Hello-World' }));
     });
   });
 
@@ -442,10 +425,6 @@ describe('GitHubReposOverviewWorkflow', () => {
         },
       });
 
-      mockOAuthWorkflow.run.mockResolvedValue({
-        workflowId: 'test-workflow-id',
-      });
-
       const result = await processor.process(workflow, { owner: 'octocat', repo: 'Hello-World' }, context);
 
       expect(result).toBeDefined();
@@ -457,10 +436,7 @@ describe('GitHubReposOverviewWorkflow', () => {
       expect(mockOAuthWorkflow.run).toHaveBeenCalledTimes(1);
       expect(mockOAuthWorkflow.run).toHaveBeenCalledWith(
         { provider: 'github', scopes: ['repo', 'read:org', 'workflow'] },
-        expect.objectContaining({
-          alias: 'oAuth',
-          callback: { transition: 'authCompleted' },
-        }),
+        { callback: { transition: 'authCompleted' } },
       );
 
       // Subsequent tools should NOT be called
@@ -570,9 +546,7 @@ describe('GitHubReposOverviewWorkflow with existing entity', () => {
     expect(result.place).toBe('end');
 
     // Verify markdown document was created after auth resume
-    expect(result.documents).toEqual(
-      expect.arrayContaining([expect.objectContaining({ className: 'MarkdownDocument' })]),
-    );
+    expect(result.documents).toEqual(expect.arrayContaining([expect.objectContaining({ documentName: 'markdown' })]));
 
     expect(mockGetAuthenticatedUser.call).toHaveBeenCalledTimes(1);
     expect(mockGetRepo.call).toHaveBeenCalledTimes(1);

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

@@ -1,16 +1,6 @@
-title: 'GitHub Agent'
-
-description: |
-  An interactive chat agent with access to GitHub.
-  Ask it to manage repositories, issues, pull requests, browse code, check CI/CD status,
-  search across GitHub, and more. Handles OAuth authentication automatically when needed —
-  the agent detects unauthorized errors and launches authentication on its own.
-
-ui:
-  widgets:
-    - widget: prompt-input
-      enabledWhen:
-        - waiting_for_user
-      options:
-        transition: userMessage
-        label: Send Message
+widget: prompt-input
+enabledWhen:
+  - waiting_for_user
+options:
+  transition: userMessage
+  label: Send Message

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

@@ -1,14 +1,7 @@
+import { Inject } from '@nestjs/common';
 import { z } from 'zod';
-import {
-  BaseWorkflow,
-  Guard,
-  Initial,
-  InjectTool,
-  InjectWorkflow,
-  ToolResult,
-  Transition,
-  Workflow,
-} from '@loopstack/common';
+import { BaseWorkflow, Guard, TEMPLATE_RENDERER, Transition, Workflow } from '@loopstack/common';
+import type { TemplateRenderFn } from '@loopstack/common';
 import {
   GitHubCreateIssueCommentTool,
   GitHubCreateIssueTool,
@@ -46,98 +39,66 @@ import {
 import { OAuthWorkflow } from '@loopstack/oauth-module';
 import { AuthenticateGitHubTask } from '../tools/authenticate-github-task.tool';
 
-@Workflow({
-  uiConfig: __dirname + '/github-agent.ui.yaml',
-})
-export class GitHubAgentWorkflow extends BaseWorkflow {
-  @InjectTool({
-    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: [
-      'gitHubListRepos',
-      'gitHubGetRepo',
-      'gitHubCreateRepo',
-      'gitHubListBranches',
-      'gitHubListIssues',
-      'gitHubGetIssue',
-      'gitHubCreateIssue',
-      'gitHubCreateIssueComment',
-      'gitHubListPullRequests',
-      'gitHubGetPullRequest',
-      'gitHubCreatePullRequest',
-      'gitHubMergePullRequest',
-      'gitHubListPrReviews',
-      'gitHubGetFileContent',
-      'gitHubCreateOrUpdateFile',
-      'gitHubListDirectory',
-      'gitHubGetCommit',
-      'gitHubListWorkflowRuns',
-      'gitHubTriggerWorkflow',
-      'gitHubGetWorkflowRun',
-      'gitHubSearchCode',
-      'gitHubSearchRepos',
-      'gitHubSearchIssues',
-      'gitHubGetAuthenticatedUser',
-      'gitHubListUserOrgs',
-      'authenticateGitHub',
-    ],
-  })
-  llmGenerateText: LlmGenerateTextTool;
-  @InjectTool({ provider: 'claude' }) llmDelegateToolCalls: LlmDelegateToolCallsTool;
-  @InjectTool({ provider: 'claude' }) llmUpdateToolResult: LlmUpdateToolResultTool;
-  @InjectTool() authenticateGitHub: AuthenticateGitHubTask;
-
-  // GitHub Repos tools
-  @InjectTool() gitHubListRepos: GitHubListReposTool;
-  @InjectTool() gitHubGetRepo: GitHubGetRepoTool;
-  @InjectTool() gitHubCreateRepo: GitHubCreateRepoTool;
-  @InjectTool() gitHubListBranches: GitHubListBranchesTool;
-
-  // GitHub Issues tools
-  @InjectTool() gitHubListIssues: GitHubListIssuesTool;
-  @InjectTool() gitHubGetIssue: GitHubGetIssueTool;
-  @InjectTool() gitHubCreateIssue: GitHubCreateIssueTool;
-  @InjectTool() gitHubCreateIssueComment: GitHubCreateIssueCommentTool;
-
-  // GitHub Pull Requests tools
-  @InjectTool() gitHubListPullRequests: GitHubListPullRequestsTool;
-  @InjectTool() gitHubGetPullRequest: GitHubGetPullRequestTool;
-  @InjectTool() gitHubCreatePullRequest: GitHubCreatePullRequestTool;
-  @InjectTool() gitHubMergePullRequest: GitHubMergePullRequestTool;
-  @InjectTool() gitHubListPrReviews: GitHubListPrReviewsTool;
-
-  // GitHub Content / Git Ops tools
-  @InjectTool() gitHubGetFileContent: GitHubGetFileContentTool;
-  @InjectTool() gitHubCreateOrUpdateFile: GitHubCreateOrUpdateFileTool;
-  @InjectTool() gitHubListDirectory: GitHubListDirectoryTool;
-  @InjectTool() gitHubGetCommit: GitHubGetCommitTool;
-
-  // GitHub Actions tools
-  @InjectTool() gitHubListWorkflowRuns: GitHubListWorkflowRunsTool;
-  @InjectTool() gitHubTriggerWorkflow: GitHubTriggerWorkflowTool;
-  @InjectTool() gitHubGetWorkflowRun: GitHubGetWorkflowRunTool;
-
-  // GitHub Search tools
-  @InjectTool() gitHubSearchCode: GitHubSearchCodeTool;
-  @InjectTool() gitHubSearchRepos: GitHubSearchReposTool;
-  @InjectTool() gitHubSearchIssues: GitHubSearchIssuesTool;
-
-  // GitHub Users & Orgs tools
-  @InjectTool() gitHubGetAuthenticatedUser: GitHubGetAuthenticatedUserTool;
-  @InjectTool() gitHubListUserOrgs: GitHubListUserOrgsTool;
-
-  @InjectWorkflow() oAuth: OAuthWorkflow;
-
+interface GitHubAgentState {
   llmResult?: LlmGenerateTextResult;
   llmMeta?: LlmResultMeta;
   delegateResult?: LlmDelegateResult;
+}
+
+@Workflow({
+  title: 'GitHub Agent',
+  description:
+    'An interactive chat agent with access to GitHub.\nAsk it to manage repositories, issues, pull requests, browse code, check CI/CD status,\nsearch across GitHub, and more. Handles OAuth authentication automatically when needed —\nthe agent detects unauthorized errors and launches authentication on its own.',
+  name: 'github_agent',
+  widget: __dirname + '/github-agent.ui.yaml',
+})
+export class GitHubAgentWorkflow extends BaseWorkflow<Record<string, unknown>, GitHubAgentState> {
+  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,
+    @Inject(TEMPLATE_RENDERER) private readonly render: TemplateRenderFn,
+  ) {
+    super();
+  }
 
-  @Initial({ to: 'waiting_for_user' })
-  async setup() {
-    await this.repository.save(
+  @Transition({ to: 'waiting_for_user' })
+  async setup(state: GitHubAgentState): Promise<GitHubAgentState> {
+    await this.documentStore.save(
       LlmMessageDocument,
       {
         role: 'user',
@@ -145,71 +106,119 @@ to let the user sign in, then retry. Be concise and format results using markdow
       },
       { meta: { hidden: true } },
     );
+    return state;
   }
 
   @Transition({ from: 'waiting_for_user', to: 'ready', wait: true, schema: z.string() })
-  async userMessage(payload: string) {
-    await this.repository.save(LlmMessageDocument, {
+  async userMessage(state: GitHubAgentState, payload: string): Promise<GitHubAgentState> {
+    await this.documentStore.save(LlmMessageDocument, {
       role: 'user',
       content: payload,
     });
+    return state;
   }
 
   @Transition({ from: 'ready', to: 'prompt_executed' })
-  async llmTurn() {
-    const result: ToolResult<LlmGenerateTextResult, LlmResultMeta> = await this.llmGenerateText.call();
-    this.llmResult = result.data;
-    this.llmMeta = result.metadata;
+  async llmTurn(state: GitHubAgentState): Promise<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',
+          ],
+        },
+      },
+    );
+    return { ...state, llmResult: result.data, llmMeta: result.metadata as LlmResultMeta | undefined };
   }
 
   @Transition({ from: 'prompt_executed', to: 'awaiting_tools', priority: 10 })
   @Guard('hasToolCalls')
-  async executeToolCalls() {
-    await this.repository.save(LlmMessageDocument, this.llmResult!.message, {
-      meta: { response: this.llmResult!.response, provider: this.llmMeta!.provider },
+  async executeToolCalls(state: GitHubAgentState): Promise<GitHubAgentState> {
+    await this.documentStore.save(LlmMessageDocument, state.llmResult!.message, {
+      meta: { response: state.llmResult!.response, provider: state.llmMeta!.provider },
     });
-    const result: ToolResult<LlmDelegateResult> = await this.llmDelegateToolCalls.call({
-      message: this.llmResult!.message,
-      callback: { transition: 'toolResultReceived' },
-    });
-    this.delegateResult = result.data;
+    const result = await this.llmDelegateToolCalls.call(
+      {
+        message: state.llmResult!.message,
+        callback: { transition: 'toolResultReceived' },
+      },
+      { config: { provider: 'claude' } },
+    );
+    return { ...state, delegateResult: result.data };
   }
 
-  hasToolCalls(): boolean {
-    return this.llmResult?.message.stopReason === 'tool_use';
+  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(payload: Record<string, unknown>) {
-    const result: ToolResult<LlmDelegateResult> = await this.llmUpdateToolResult.call({
-      delegateResult: this.delegateResult!,
-      completedTool: payload,
-    });
-    this.delegateResult = result.data;
+  async toolResultReceived(state: GitHubAgentState, payload: Record<string, unknown>): Promise<GitHubAgentState> {
+    const result = await this.llmUpdateToolResult.call(
+      {
+        delegateResult: state.delegateResult!,
+        completedTool: payload,
+      },
+      { config: { provider: 'claude' } },
+    );
+    return { ...state, delegateResult: result.data };
   }
 
   @Transition({ from: 'awaiting_tools', to: 'ready' })
   @Guard('allToolsComplete')
-  async allToolsCompleteTransition() {
-    await this.repository.save(LlmMessageDocument, {
+  async allToolsCompleteTransition(state: GitHubAgentState): Promise<GitHubAgentState> {
+    await this.documentStore.save(LlmMessageDocument, {
       role: 'user',
-      content: this.delegateResult!.toolResults.map((tr) => ({
+      content: state.delegateResult!.toolResults.map((tr) => ({
         type: 'tool_result' as const,
         toolCallId: tr.toolCallId,
         content: tr.content ?? '',
         isError: tr.isError ?? false,
       })),
     });
+    return state;
   }
 
-  allToolsComplete(): boolean {
-    return this.delegateResult?.allCompleted ?? false;
+  allToolsComplete(state: GitHubAgentState): boolean {
+    return state.delegateResult?.allCompleted ?? false;
   }
 
   @Transition({ from: 'prompt_executed', to: 'waiting_for_user' })
-  async respond() {
-    await this.repository.save(LlmMessageDocument, this.llmResult!.message, {
-      meta: { response: this.llmResult!.response, provider: this.llmMeta!.provider },
+  async respond(state: GitHubAgentState): Promise<GitHubAgentState> {
+    await this.documentStore.save(LlmMessageDocument, state.llmResult!.message, {
+      meta: { response: state.llmResult!.response, provider: state.llmMeta!.provider },
     });
+    return state;
   }
 }