feat: add agent mode for automation scenarios (#337)

* feat: add agent mode for automation scenarios

- Add agent mode that always triggers without checking for mentions
- Implement Mode interface with support for mode-specific tool configuration
- Add getAllowedTools() and getDisallowedTools() methods to Mode interface
- Simplify tests by combining related test cases
- Update documentation and examples to include agent mode
- Fix TypeScript imports to prevent circular dependencies

Agent mode is designed for automation and workflow_dispatch scenarios
where Claude should always run without requiring trigger phrases.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Minor update to readme (from @main to @beta)

* Since workflow_dispatch isn't in the base action, update the examples accordingly

* minor formatting issue

* Update to say beta instead of main

* Fix missed tracking comment to be false

---------

Co-authored-by: km-anthropic <km-anthropic@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>

test/modes/agent.test.ts

@@ -0,0 +1,82 @@
+import { describe, test, expect, beforeEach } from "bun:test";
+import { agentMode } from "../../src/modes/agent";
+import type { ParsedGitHubContext } from "../../src/github/context";
+import { createMockContext } from "../mockContext";
+
+describe("Agent Mode", () => {
+  let mockContext: ParsedGitHubContext;
+
+  beforeEach(() => {
+    mockContext = createMockContext({
+      eventName: "workflow_dispatch",
+      isPR: false,
+    });
+  });
+
+  test("agent mode has correct properties and behavior", () => {
+    // Basic properties
+    expect(agentMode.name).toBe("agent");
+    expect(agentMode.description).toBe(
+      "Automation mode that always runs without trigger checking",
+    );
+    expect(agentMode.shouldCreateTrackingComment()).toBe(false);
+
+    // Tool methods return empty arrays
+    expect(agentMode.getAllowedTools()).toEqual([]);
+    expect(agentMode.getDisallowedTools()).toEqual([]);
+
+    // Always triggers regardless of context
+    const contextWithoutTrigger = createMockContext({
+      eventName: "workflow_dispatch",
+      isPR: false,
+      inputs: {
+        ...createMockContext().inputs,
+        triggerPhrase: "@claude",
+      },
+      payload: {} as any,
+    });
+    expect(agentMode.shouldTrigger(contextWithoutTrigger)).toBe(true);
+  });
+
+  test("prepareContext includes all required data", () => {
+    const data = {
+      commentId: 789,
+      baseBranch: "develop",
+      claudeBranch: "claude/automated-task",
+    };
+
+    const context = agentMode.prepareContext(mockContext, data);
+
+    expect(context.mode).toBe("agent");
+    expect(context.githubContext).toBe(mockContext);
+    expect(context.commentId).toBe(789);
+    expect(context.baseBranch).toBe("develop");
+    expect(context.claudeBranch).toBe("claude/automated-task");
+  });
+
+  test("prepareContext works without data", () => {
+    const context = agentMode.prepareContext(mockContext);
+
+    expect(context.mode).toBe("agent");
+    expect(context.githubContext).toBe(mockContext);
+    expect(context.commentId).toBeUndefined();
+    expect(context.baseBranch).toBeUndefined();
+    expect(context.claudeBranch).toBeUndefined();
+  });
+
+  test("agent mode triggers for all event types", () => {
+    const events = [
+      "push",
+      "schedule",
+      "workflow_dispatch",
+      "repository_dispatch",
+      "issue_comment",
+      "pull_request",
+    ];
+
+    events.forEach((eventName) => {
+      const context = createMockContext({ eventName, isPR: false });
+      expect(agentMode.shouldTrigger(context)).toBe(true);
+    });
+  });
+});

test/modes/registry.test.ts

@@ -1,6 +1,8 @@
 import { describe, test, expect } from "bun:test";
-import { getMode, isValidMode, type ModeName } from "../../src/modes/registry";
+import { getMode, isValidMode } from "../../src/modes/registry";
+import type { ModeName } from "../../src/modes/types";
 import { tagMode } from "../../src/modes/tag";
+import { agentMode } from "../../src/modes/agent";
 
 describe("Mode Registry", () => {
   test("getMode returns tag mode by default", () => {
@@ -9,20 +11,26 @@ describe("Mode Registry", () => {
     expect(mode.name).toBe("tag");
   });
 
+  test("getMode returns agent mode", () => {
+    const mode = getMode("agent");
+    expect(mode).toBe(agentMode);
+    expect(mode.name).toBe("agent");
+  });
+
   test("getMode throws error for invalid mode", () => {
     const invalidMode = "invalid" as unknown as ModeName;
     expect(() => getMode(invalidMode)).toThrow(
-      "Invalid mode 'invalid'. Valid modes are: 'tag'. Please check your workflow configuration.",
+      "Invalid mode 'invalid'. Valid modes are: 'tag', 'agent'. Please check your workflow configuration.",
     );
   });
 
-  test("isValidMode returns true for tag mode", () => {
+  test("isValidMode returns true for all valid modes", () => {
     expect(isValidMode("tag")).toBe(true);
+    expect(isValidMode("agent")).toBe(true);
   });
 
   test("isValidMode returns false for invalid mode", () => {
     expect(isValidMode("invalid")).toBe(false);
     expect(isValidMode("review")).toBe(false);
-    expect(isValidMode("freeform")).toBe(false);
   });
 });