feat: add Asana bot integration

.github/workflows/ci.yml

@@ -299,6 +299,9 @@ jobs:
       - name: Run linear-bot tests
         run: npm test -w @open-inspect/linear-bot
 
+      - name: Run asana-bot tests
+        run: npm test -w @open-inspect/asana-bot
+
   test-python-sandbox-runtime:
     name: Test (Python - sandbox-runtime)
     runs-on: ubuntu-latest

docs/integrations/ASANA.md

@@ -0,0 +1,221 @@
+# Asana Integration
+
+Open-Inspect's Asana integration starts coding sessions from Asana tasks. Assign tasks to the bot
+user or mention the bot in comments to start work, then use Asana for progress, results, and
+follow-ups.
+
+This guide is for people using the Asana integration day to day. If you are installing the Asana bot
+or deploying the worker, start with the
+[Asana Bot setup guide](../../packages/asana-bot/README.md#setup).
+
+---
+
+## Quick Start
+
+1. Open the Asana task you want Open-Inspect to work on.
+2. Assign the task to the bot user.
+3. Or mention the bot in a comment (available if the task's project has webhooks registered).
+4. Include `owner/repo` if the task could match more than one repository.
+5. Use **View Session** to watch the full session.
+6. Send follow-ups as comments on the same task (active sessions continue).
+
+---
+
+## What Asana Can Do
+
+| Workflow               | How it works                                                     |
+| ---------------------- | ---------------------------------------------------------------- |
+| Start from assignment  | Assign the task to the bot user                                  |
+| Start from a comment   | Mention the bot in a comment (if webhooks are registered)        |
+| Continue active work   | Send a follow-up comment on the same task                        |
+| Stop or cancel work    | Unassign the bot from the task or mark it complete               |
+| Resolve the repository | Let Open-Inspect infer the repo, or include `owner/repo` in task |
+| Follow progress        | Open the full session with **View Session** for detailed logs    |
+
+Start work by assigning the task to the bot user, or mentioning the bot in a comment on a task with
+an active session.
+
+---
+
+## Start, Continue, or Stop Work
+
+### From Assignment
+
+Assign the task to the bot user when the task title and description already describe the work:
+
+```
+Assignee: [bot user]
+```
+
+Assignment works best when the task includes:
+
+- A clear title and description
+- Acceptance criteria or expected result
+- The target repository, if it is ambiguous
+- Whether the bot should open a pull request
+
+The bot picks up the assignment and starts working immediately.
+
+### From a Comment Mention
+
+Mention the bot in a comment on a task when you want to start or continue work:
+
+```text
+@OpenInspect can you refactor this component as described above?
+```
+
+The bot uses the task, description, and recent comments as context. Your mention becomes the work
+instruction, so include what you want done.
+
+This requires the task's project to have webhooks registered. If the project webhook is not set up,
+use assignment instead.
+
+### Follow-Up Messages
+
+Follow-up comments on a task with an active Open-Inspect session go to that session. Open-Inspect
+adds recent agent output as context.
+
+Task-to-session mappings are kept for several days. If the mapping has expired, or if the previous
+session was stopped, a new assignment or mention may start a new session.
+
+### Stop or Cancel
+
+Stopping work:
+
+- **Unassign** the bot user from the task (remove from assignees)
+- **Mark the task complete** (set completed to true)
+- The session stops immediately; the sandbox is cleaned up
+
+Either action stops the associated Open-Inspect sandbox session.
+
+---
+
+## Repository Selection
+
+Before starting work, Open-Inspect chooses a repo from the task's projects, description, and
+available repo metadata.
+
+If the task could match more than one repository, include the intended repository name in the task
+or follow-up comment:
+
+```text
+Please handle this in acme/billing-api.
+```
+
+If Open-Inspect asks for clarification, reply with `owner/repo`. That answer is used on the next
+resolution attempt.
+
+Admins can map Asana projects to repositories. See
+[Configure Repo Mapping](../../packages/asana-bot/README.md#6-configure-repo-mapping-optional) for
+details.
+
+---
+
+## What You See
+
+| Indicator            | What it means                                                      |
+| -------------------- | ------------------------------------------------------------------ |
+| Task assigned        | Open-Inspect acknowledges the assignment and is analyzing the task |
+| "Working on..." note | A session has started and Open-Inspect is coding                   |
+| Follow-up comments   | Open-Inspect processes your replies in the active session          |
+| PR link              | The session finished; Open-Inspect posted a PR link                |
+| Error comment        | The session failed or could not continue                           |
+
+When a session starts, Open-Inspect posts a **"Working on owner/repo..."** comment on the task. When
+the agent opens a pull request, a **Pull Request link** comment is posted when the session finishes.
+
+Open the web session for live output, logs, artifacts, and file changes. Asana shows status comments
+but does not update task status, labels, priority, or project.
+
+---
+
+## Settings
+
+Open the web app and go to **Settings > Integrations > Asana** to configure the Asana Bot.
+
+| Setting                   | What it controls                                      |
+| ------------------------- | ----------------------------------------------------- |
+| Default model and effort  | Model and reasoning depth for Asana-started sessions  |
+| Task session instructions | Extra guidance appended to Asana task prompts         |
+| Allow user preferences    | Whether users can override the model with preferences |
+| Repository overrides      | Per-repository defaults for model and reasoning       |
+
+If no Asana settings are configured, all accessible repositories are in scope, user preferences are
+allowed, and the deployment default model is used.
+
+Model selection uses this priority, highest to lowest:
+
+1. Asana user preference (when allowed).
+2. Repository override or global Asana default.
+3. Deployment default model.
+
+Asana user preferences are currently admin/API-managed, not set from a self-service Asana screen.
+
+---
+
+## Admin and Safety Notes
+
+- Asana webhooks are verified before Open-Inspect acts on them.
+- Asana Personal Access Tokens and webhook secrets stay server-side.
+- Asana does not provide Git credentials. Repository access still comes from the deployment's
+  configured source-control integration, such as the GitHub App installation.
+- Task titles, descriptions, comments, and prompts may be sent to the coding agent. Do not include
+  secrets.
+
+---
+
+## Troubleshooting
+
+### The bot does not appear in Asana
+
+Confirm the Asana bot user is created and available in your workspace. If you cannot find the bot
+user in the assignee list, check with your admin that the user account was set up correctly.
+
+### A task assignment does not start
+
+Make sure the task is assigned to the bot user (check the Assignees field). Also verify that
+Open-Inspect can resolve and access the target repository.
+
+### Comment mentions do not work
+
+Comment mentions (e.g., `@OpenInspect ...`) require the task's project to have a project webhook
+registered. If mentions do not trigger work, either:
+
+- Use **assignment** instead (always works)
+- Ask an admin to register webhooks for the project
+
+### Open-Inspect asks which repository to use
+
+Reply with `owner/repo` in a comment. To avoid future prompts, add the repo to the task description,
+or ask an admin to map the Asana project to a repository.
+
+### I see a status comment but need full logs
+
+Open **View Session** (linked in the "Working on..." comment). Asana shows status and completion
+activity, while detailed logs, transcripts, artifacts, and file changes live in the Open-Inspect web
+session.
+
+### The wrong model was used
+
+Check **Settings > Integrations > Asana**. Repository overrides and user preferences can affect
+model selection. Changes apply to new Asana-started sessions.
+
+### The wrong repository was used
+
+Check project repo mappings, task description, repository metadata, and the selected repository
+scope. If a task is ambiguous, include the intended `owner/repo` in the task description or a
+follow-up comment.
+
+### The bot is active in too many repositories
+
+Limit the source-control installation to intended repositories, or set **Repository Scope** in Asana
+integration settings to **Selected repositories**.
+
+### Webhooks deleted or not processing
+
+Asana automatically deletes webhooks after 24 hours of consecutive failures. If webhooks are missing
+or not processing:
+
+1. Check that the bot user PAT is valid and has `webhooks:manage` scope
+2. Ask an admin to re-run the webhook setup (see
+   [Establish Webhooks](../../packages/asana-bot/README.md#5-establish-webhooks))