From 392524e14954fa9d617265887ffca1eaaa9d7f4a Mon Sep 17 00:00:00 2001 From: "codegen-sh[bot]" <131295404+codegen-sh[bot]@users.noreply.github.com> Date: Wed, 16 Jul 2025 17:19:06 +0000 Subject: [PATCH 1/2] Add comprehensive documentation for Slack/Linear interrupt system - Document how real-time interrupts work during agent execution - Explain technical implementation with BaseRunner and TaskTimeline - Include examples for both Slack and Linear workflows - Add best practices and troubleshooting guidance - Update docs.json navigation to include new interrupts page --- docs/capabilities/interrupts.mdx | 174 +++++++++++++++++++++++++++++++ docs/docs.json | 2 +- 2 files changed, 175 insertions(+), 1 deletion(-) create mode 100644 docs/capabilities/interrupts.mdx diff --git a/docs/capabilities/interrupts.mdx b/docs/capabilities/interrupts.mdx new file mode 100644 index 000000000..dc715548b --- /dev/null +++ b/docs/capabilities/interrupts.mdx @@ -0,0 +1,174 @@ +--- +title: "Interrupts" +description: "How Codegen handles real-time interrupts from Slack and Linear while working" +--- + +## Overview + +Codegen supports **real-time interrupts** that allow users to send additional messages or clarifications while the agent is actively working on a task. This feature enables dynamic, conversational interactions where users can provide feedback, corrections, or additional context without waiting for the agent to complete its current work. + +## How Interrupts Work + +When Codegen is actively processing a request, users can send follow-up messages through supported channels (Slack, Linear) that will be immediately delivered to the running agent as "interrupt messages." + +### Key Features + +- **Real-time delivery**: Messages are delivered immediately to the active agent +- **Context preservation**: The agent maintains full context of the original task +- **Immediate acknowledgment**: Codegen typically responds quickly to acknowledge the interrupt +- **Seamless integration**: The agent incorporates new information into its current workflow + +## Supported Channels + +### Slack Interrupts + +In Slack, you can send interrupt messages by: + +1. **Replying in the thread** where Codegen is working +2. **Mentioning @codegen** with additional context +3. **Sending follow-up messages** in the same channel + +**Example:** +``` +User: @codegen can you fix the login bug? +Codegen: I'll fix the login bug! 🔧 [starts working] +User: Actually, make sure to also handle the password reset flow +Codegen: Got it! I'll include the password reset flow in my fix 👍 +``` + +### Linear Interrupts + +In Linear, interrupts work through: + +1. **Adding comments** to the issue Codegen is working on +2. **Updating the issue description** with additional requirements +3. **Changing issue priority or labels** (triggers re-evaluation) + +**Example:** +``` +Issue: Fix authentication system +Codegen: Working on the authentication fix... +[User adds comment]: "Please also add 2FA support" +Codegen: I see you've added 2FA requirements - incorporating that now! +``` + +## Technical Implementation + +### Interrupt Flow + +1. **Message Detection**: When a user sends a message in an active agent context +2. **Interrupt Storage**: The message is stored in the agent's `interrupt_messages` queue +3. **Agent Notification**: The running agent checks for new interrupts between operations +4. **Message Processing**: Interrupts are processed as `[INTERRUPT]` prefixed messages +5. **Response Integration**: The agent incorporates the new information into its workflow + +### Message Format + +Interrupt messages are structured as: + +```json +{ + "content": { + "message": "User's interrupt message", + "file_messages": [] // Optional file attachments + }, + "actor": { + "name": "User Name", + "email": "user@example.com", + "avatar_url": "https://..." + }, + "source": { + "url": "https://linear.app/issue/...", + "display_name": "Issue Title" + } +} +``` + +### Agent Processing + +When an interrupt is received, the agent: + +1. **Acknowledges** the interrupt with a quick response +2. **Evaluates** how the new information affects the current task +3. **Adjusts** its approach or adds new requirements +4. **Continues** working with the updated context + +## Best Practices + +### For Users + + +**Send interrupts early**: If you realize you need to add context or change requirements, send the message immediately rather than waiting for completion. + + +- **Be specific**: Clearly state what you want to add or change +- **Provide context**: Explain how the new information relates to the original request +- **Use @mentions**: In Slack, use @codegen to ensure the message is properly routed + +### Common Use Cases + +1. **Adding requirements**: "Also make sure to add error handling" +2. **Providing clarification**: "By 'users' I meant admin users specifically" +3. **Changing scope**: "Actually, let's focus on the mobile version first" +4. **Sharing additional context**: "Here's the error log I forgot to include" +5. **Course correction**: "That approach won't work, try using the new API instead" + +## Limitations + +- **Processing order**: Interrupts are processed in the order they're received +- **Context switching**: Very frequent interrupts may slow down overall progress +- **Channel-specific**: Interrupts only work within the same channel/issue where work started + +## Troubleshooting + +### Interrupt Not Acknowledged + +If your interrupt isn't acknowledged: + +1. **Check the channel**: Ensure you're messaging in the same thread/issue +2. **Wait briefly**: The agent may be in the middle of a long operation +3. **Use @mentions**: In Slack, explicitly mention @codegen +4. **Check agent status**: The agent may have completed or encountered an error + +### Message Not Incorporated + +If your interrupt seems ignored: + +1. **Be more explicit**: Clearly state what you want changed +2. **Reference the original task**: Connect your interrupt to the current work +3. **Follow up**: Send a clarifying message if needed + +## Examples + +### Slack Thread Example + +``` +User: @codegen create a user registration form +Codegen: I'll create a user registration form! 📝 [working...] + +User: Make sure it includes email verification +Codegen: Got it! Adding email verification to the registration form 📧 + +User: And add password strength requirements +Codegen: Perfect! I'll include password strength validation as well 🔒 +``` + +### Linear Issue Example + +``` +Linear Issue: "Implement search functionality" +Codegen: Working on search functionality... + +[User adds comment]: "Please include filters for date and category" +Codegen: I see you've added filter requirements - implementing date and category filters now! + +[User adds comment]: "Also add sorting options" +Codegen: Adding sorting options to the search as well! 📊 +``` + +## Related Features + +- [Wake-up Triggers](/capabilities/wake-up) - How to initially trigger Codegen +- [Slack Integration](/integrations/slack) - Complete Slack setup and usage +- [Linear Integration](/integrations/linear) - Complete Linear setup and usage + diff --git a/docs/docs.json b/docs/docs.json index 9045a6bde..f5d8f21a6 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -26,7 +26,7 @@ }, { "group": "Capabilities", - "pages": ["capabilities/capabilities", "capabilities/wake-up"] + "pages": ["capabilities/capabilities", "capabilities/wake-up", "capabilities/interrupts"] }, { "group": "Integrations", From 977d79f7102acd9c42d9fc93d5d38390ff4693e1 Mon Sep 17 00:00:00 2001 From: "codegen-sh[bot]" <131295404+codegen-sh[bot]@users.noreply.github.com> Date: Wed, 16 Jul 2025 17:23:07 +0000 Subject: [PATCH 2/2] Clarify mention requirements and remove technical implementation - Add clear warning that @codegen mentions are required in Slack channels (not DMs) - Add note that Linear responds automatically unless other users are tagged - Remove technical implementation section for user-facing docs - Update best practices and troubleshooting with mention requirements --- docs/capabilities/interrupts.mdx | 56 ++++++++------------------------ 1 file changed, 13 insertions(+), 43 deletions(-) diff --git a/docs/capabilities/interrupts.mdx b/docs/capabilities/interrupts.mdx index dc715548b..a91b52ff2 100644 --- a/docs/capabilities/interrupts.mdx +++ b/docs/capabilities/interrupts.mdx @@ -28,6 +28,10 @@ In Slack, you can send interrupt messages by: 2. **Mentioning @codegen** with additional context 3. **Sending follow-up messages** in the same channel + +**Important**: You **must** mention `@codegen` in your interrupt messages for Codegen to respond in Slack channels, unless you're in a direct message (DM) with Codegen where it will respond automatically. + + **Example:** ``` User: @codegen can you fix the login bug? @@ -44,6 +48,10 @@ In Linear, interrupts work through: 2. **Updating the issue description** with additional requirements 3. **Changing issue priority or labels** (triggers re-evaluation) + +**Note**: Codegen will respond automatically to your comments in Linear unless another user is tagged in the same comment. + + **Example:** ``` Issue: Fix authentication system @@ -52,46 +60,7 @@ Codegen: Working on the authentication fix... Codegen: I see you've added 2FA requirements - incorporating that now! ``` -## Technical Implementation - -### Interrupt Flow - -1. **Message Detection**: When a user sends a message in an active agent context -2. **Interrupt Storage**: The message is stored in the agent's `interrupt_messages` queue -3. **Agent Notification**: The running agent checks for new interrupts between operations -4. **Message Processing**: Interrupts are processed as `[INTERRUPT]` prefixed messages -5. **Response Integration**: The agent incorporates the new information into its workflow - -### Message Format - -Interrupt messages are structured as: - -```json -{ - "content": { - "message": "User's interrupt message", - "file_messages": [] // Optional file attachments - }, - "actor": { - "name": "User Name", - "email": "user@example.com", - "avatar_url": "https://..." - }, - "source": { - "url": "https://linear.app/issue/...", - "display_name": "Issue Title" - } -} -``` - -### Agent Processing - -When an interrupt is received, the agent: -1. **Acknowledges** the interrupt with a quick response -2. **Evaluates** how the new information affects the current task -3. **Adjusts** its approach or adds new requirements -4. **Continues** working with the updated context ## Best Practices @@ -103,7 +72,8 @@ When an interrupt is received, the agent: - **Be specific**: Clearly state what you want to add or change - **Provide context**: Explain how the new information relates to the original request -- **Use @mentions**: In Slack, use @codegen to ensure the message is properly routed +- **Use @mentions in Slack**: Always mention @codegen in Slack channels (not needed in DMs) +- **No mentions needed in Linear**: Codegen responds automatically unless other users are tagged ### Common Use Cases @@ -127,8 +97,9 @@ If your interrupt isn't acknowledged: 1. **Check the channel**: Ensure you're messaging in the same thread/issue 2. **Wait briefly**: The agent may be in the middle of a long operation -3. **Use @mentions**: In Slack, explicitly mention @codegen -4. **Check agent status**: The agent may have completed or encountered an error +3. **Use @mentions in Slack**: Make sure you mentioned @codegen (required in channels, not DMs) +4. **Check for other tags in Linear**: If you tagged other users, Codegen won't respond automatically +5. **Check agent status**: The agent may have completed or encountered an error ### Message Not Incorporated @@ -171,4 +142,3 @@ Codegen: Adding sorting options to the search as well! 📊 - [Wake-up Triggers](/capabilities/wake-up) - How to initially trigger Codegen - [Slack Integration](/integrations/slack) - Complete Slack setup and usage - [Linear Integration](/integrations/linear) - Complete Linear setup and usage -