Your lightweight open-source personal agent.
Python agent-frameworkai-agentai-agentschatbotchatopsdiscord-botllm-agentsllmslocal-llmmcpmodel-context-protocolmulti-agentopenai-compatibleopenclawpersonal-ai-assistantpythonself-hostedtelegram-bot-ai-assistantwebuiworkflow-automation
feat(channels): add native Linear agent channel
chengyongrue9414da24355
diff --git a/README.md b/README.mdindex e32bf821c..0308d304f 100644--- a/README.md+++ b/README.md@@ -43,7 +43,7 @@| Install nanobot with no terminal/config background | [Start Without Technical Background](./docs/start-without-technical-background.md) || Install quickly and get one CLI reply | [Install](#-install) and [Quick Start](#-quick-start) || Open the bundled browser UI | [WebUI](#-webui) |-| Connect Telegram, Discord, WeChat, Slack, Email, Mattermost, or another chat app | [Chat Apps](./docs/chat-apps.md) |+| Connect Telegram, Discord, WeChat, Slack, Email, Mattermost, Linear, or another channel | [Chat Apps](./docs/chat-apps.md) || Configure providers, fallback models, Langfuse, MCP, web tools, or security | [Docs](./docs/README.md) and [Configuration](./docs/configuration.md) || Understand or extend the internals | [Architecture](./docs/architecture.md) and [Development](./docs/development.md) || Deploy to the cloud or keep nanobot running as a service | [Deployment](./docs/deployment.md) |@@ -53,7 +53,7 @@nanobot is a self-hosted personal AI agent runtime. It can:- run in a browser WebUI or terminal-- connect to Telegram, Discord, Slack, WeChat, Email, Mattermost, and other chat apps+- connect to Telegram, Discord, Slack, WeChat, Email, Mattermost, Linear, and other channels- use tools such as files, shell, web search, web fetch, MCP, cron, image generation, and subagents- keep session history and long-term memory through Dream- run long-horizon goals and scheduled automations@@ -63,7 +63,7 @@ nanobot is a self-hosted personal AI agent runtime. It can:## 💡 Why nanobot- **Persistent workflows**: goals, memory, tools, and chat context survive long-running work.-- **Chat-native reach**: WebUI, API, Telegram, Feishu, Slack, Discord, Teams, email, and Mattermost.+- **Chat-native reach**: WebUI, API, Telegram, Feishu, Slack, Discord, Teams, email, Mattermost, and Linear.- **Model freedom**: OpenAI-compatible APIs, local LLMs, image generation, search, and fallbacks.- **Small core**: readable internals with MCP, memory, deployment, and automation built in.- **Own your stack**: inspect, customize, self-host, and extend without a giant platform.diff --git a/docs/chat-apps.md b/docs/chat-apps.mdindex 91f8dd53d..e87dcac8a 100644--- a/docs/chat-apps.md+++ b/docs/chat-apps.md@@ -1,6 +1,6 @@# Chat Apps for Self-Hosted AI Agents-Connect nanobot to Telegram, Discord, Slack, WeChat, Email, Mattermost, and+Connect nanobot to Telegram, Discord, Slack, WeChat, Email, Mattermost, Linear, andother chat platforms. This page is the full chat-channel reference. If you wanta focused setup path for one platform, start with a guide:@@ -15,6 +15,7 @@ a focused setup path for one platform, start with a guide:| QQ | [Build a QQ AI Agent with nanobot](./guides/qq-ai-agent.md) || Email | [Build an Email AI Agent with nanobot](./guides/email-ai-agent.md) || Mattermost | [Build a Mattermost AI Agent with nanobot](./guides/mattermost-ai-agent.md) |+| Linear | [Use nanobot as a native Linear agent](./guides/linear-agent.md) |Want to build your own channel? See the [Channel Package Guide](./channel-package-guide.md).@@ -105,6 +106,32 @@ If `nanobot channels status` does not show the channel as enabled, the config sn| **Microsoft Teams** | App ID + App Password + public HTTPS endpoint || **Mochat** | Claw token (auto-setup available) || **Signal** | signal-cli daemon + phone number |+| **Linear** | Private OAuth app + public HTTPS callback URL |++<details id="linear">+<summary><b>Linear</b></summary>++Linear is a native Agent channel rather than a comment bot. A user starts a task+by explicitly mentioning the installed nanobot app in an issue. Follow-up prompts+inside that Agent Session continue the same nanobot session without another+mention. Ordinary issue comments do not invoke nanobot.++The native Agent API is webhook-based. Linear must reach a stable HTTPS URL, but+the machine running nanobot does not need its own public IP address: a reverse+proxy, Cloudflare Tunnel, Tailscale Funnel, or another HTTPS tunnel can forward+the public URL to nanobot's local listener.++The recommended setup is **Settings → Channels → Linear**. Save the public URL+first to reveal a prefilled private OAuth app link, create the app, copy its Client+ID, Client Secret, and Webhook Signing Secret back into nanobot, save again, then+choose **Connect Linear**. OAuth requests only `read`, `write`, and+`app:mentionable`; it deliberately does not request `app:assignable` so a new task+must begin with an @mention.++See the [native Linear agent guide](./guides/linear-agent.md) for the complete+setup, tunnel examples, security model, and troubleshooting.++</details><details><summary><b>Telegram</b></summary>diff --git a/docs/guides/README.md b/docs/guides/README.mdindex a21c3951e..8bc53bb6b 100644--- a/docs/guides/README.md+++ b/docs/guides/README.md@@ -28,6 +28,7 @@ Use **Settings → Channels** in the WebUI for guided setup. These guides explai| Connect QQ | [QQ AI agent](./qq-ai-agent.md) || Connect Email | [Email AI agent](./email-ai-agent.md) || Connect Mattermost | [Mattermost AI agent](./mattermost-ai-agent.md) |+| Connect Linear | [Native Linear agent](./linear-agent.md) |## Integrate from Codediff --git a/docs/guides/linear-agent.md b/docs/guides/linear-agent.mdnew file mode 100644index 000000000..9400905cb--- /dev/null+++ b/docs/guides/linear-agent.md@@ -0,0 +1,265 @@+# Connect nanobot as a Native Linear Agent++This guide takes you from an empty Linear channel configuration to a working+@mention in an issue. The recommended path uses the nanobot WebUI and a+pre-filled Linear app manifest, so you do not need to enter callback URLs or+webhook subscriptions by hand.++> [!NOTE]+> Linear's Agent APIs are currently a Developer Preview. Their schema may+> change. Keep nanobot current when you use this channel.++## What this channel does++- A new task starts only when someone explicitly @mentions the installed app.+- An ordinary issue comment does not invoke nanobot.+- A follow-up inside the existing Agent Session continues the same nanobot+ session without another @mention.+- Linear's stop control cancels the active nanobot turn.+- nanobot reports its acknowledgement, tool activity, reasoning, and final+ answer as native Linear Agent Activities.++The OAuth request includes `app:mentionable` and deliberately excludes+`app:assignable`. Do not add `app:assignable` if every new task must start with+an @mention.++Linear MCP is optional. Add it when the agent also needs tools for searching or+changing Linear issues. MCP does not replace this channel's OAuth installation,+webhook, or Agent Session transport.++## Before you start++Prepare these four things:++| Requirement | What you need |+|---|---|+| Working nanobot | `nanobot agent -m "Hello"` returns a response |+| Linear access | Permission to create a private OAuth app; a workspace admin must approve its installation |+| Public HTTPS origin | A stable address such as `https://nanobot.example.com` |+| Local route | The public address forwards to nanobot's Linear listener, which defaults to port `3979` |++The public address is an **origin**, not a complete endpoint. Enter+`https://nanobot.example.com`, not+`https://nanobot.example.com/linear/webhook`.++The four network fields have different jobs:++| nanobot field | Who uses it | Recommended value |+|---|---|---|+| **Public HTTPS URL** | Linear calls this address over the internet | Your stable HTTPS origin |+| **Listen host** | nanobot binds this local interface | `127.0.0.1` for a same-machine proxy; `0.0.0.0` when a container or another host must reach it |+| **Listen port** | The proxy or tunnel forwards to this local port | Keep `3979` unless it conflicts with another service |+| **Webhook/OAuth paths** | nanobot distinguishes webhook delivery from OAuth callbacks | Keep the defaults unless your proxy requires different paths |++### Webhook and networking requirements++The native Linear Agent transport requires a webhook; there is no polling mode.+The OAuth callback also needs to reach the same nanobot instance.++You do **not** need a public IP address. A reverse proxy or HTTPS tunnel can+forward a public hostname to `127.0.0.1:3979`. Cloudflare Tunnel, Tailscale+Funnel, Caddy, nginx, and similar tools can all provide this route. Use a stable+hostname for normal use: if the hostname changes, you must update both URLs in+the Linear app.++Choose the simplest option that matches your deployment:++| Your deployment | Recommended route |+|---|---|+| Home server, laptop, or a network behind NAT | A named HTTPS tunnel with a fixed hostname |+| VPS with a domain and existing HTTPS proxy | Add a reverse-proxy route to `127.0.0.1:3979` |+| Docker or Kubernetes | Route the ingress or proxy to the container's port `3979`; keep the public URL on the ingress |+| Short local test | A temporary HTTPS tunnel works, but you must recreate or edit the Linear app when its hostname changes |++With the default paths, the route must preserve these two requests:++```text+https://nanobot.example.com/linear/oauth/callback -> 127.0.0.1:3979+https://nanobot.example.com/linear/webhook -> 127.0.0.1:3979+```++If the proxy or tunnel runs on the same machine, set the advanced **Listen+host** field to `127.0.0.1` so the listener is not exposed directly on the local+network. Containers and separate reverse-proxy hosts may require `0.0.0.0`.+The Linear listener serves plain HTTP locally; terminate HTTPS at the proxy or+tunnel instead of exposing port `3979` directly to the internet.++## Recommended setup in the WebUI++Keep `nanobot webui` running throughout the setup.++### 1. Save the public address++1. Open **Settings → Channels → Linear**.+2. Enter your stable origin in **Public HTTPS URL**, for example+ `https://nanobot.example.com`.+3. Leave the three OAuth credential fields empty for now.+4. Select **Save settings**. nanobot saves the partial configuration and shows+ **Create prefilled Linear app**.++Saving a partial configuration at this point is expected. You will create the+credentials in the next step.++### 2. Create the Linear app++1. Select **Create prefilled Linear app**. Sign in to the Linear workspace in+ which you want to create the app.+2. Review the pre-filled form. It should describe a **private** app and contain:++ ```text+ Redirect URI: https://nanobot.example.com/linear/oauth/callback+ Webhook URL: https://nanobot.example.com/linear/webhook+ Webhook types: AgentSessionEvent, PermissionChange, OAuthAuthorization+ ```++3. Choose a short, recognizable app name and icon if you want to customize how+ nanobot appears in Linear.+4. Create the app.++Do not add a `Comment` webhook subscription. Linear delivers new @mentions and+Agent Session follow-ups through `AgentSessionEvent`; subscribing to comments+would add events that this channel intentionally ignores.++### 3. Copy the three credentials into nanobot++In the new Linear app's settings, copy these values:++| Linear value | nanobot field |+|---|---|+| Client ID | **OAuth client ID** |+| Client Secret | **OAuth client secret** |+| Webhook signing secret | **Webhook signing secret** |++Return to **Settings → Channels → Linear**, paste all three values, and select+**Save settings** again. A successful validation lists the complete webhook and+OAuth callback URLs.++Treat the Client Secret and Webhook signing secret like passwords. They belong+only in the nanobot configuration and the Linear application settings.++### 4. Authorize the workspace++1. Select **Connect Linear**.+2. Open the displayed authorization link, or scan the QR code.+3. Choose the workspace and approve the installation as a workspace admin.+4. Return to nanobot and wait for **Linear is connected**.++nanobot enables the channel automatically after authorization. The gateway must+remain running so Linear can deliver webhooks. To replace an authorization, use+the reconnect action and approve it again.++The pre-filled manifest creates a private app for the current workspace. A+distributable OAuth app can authorize additional workspaces; nanobot stores and+refreshes each workspace installation separately.++### 5. Test the first task++1. Open an issue in the connected Linear workspace.+2. Add a comment that @mentions the app and includes a request, for example:++ ```text+ @nanobot summarize the likely cause and suggest the next diagnostic step+ ```++3. Open the Agent Session. You should first see a starting acknowledgement,+ followed by agent activity and a final response.+4. Send a follow-up inside that Agent Session. You do not need to @mention the+ app again there.++If **Allowed Linear users** is empty, the first mention returns a nanobot pairing+code. Approve the pending request in the WebUI pairing dialog, then repeat the+prompt in the same Agent Session. For a static allowlist, enter Linear user IDs+in **Allowed Linear users**. Enter `*` only if every member of every connected+workspace should be able to invoke the agent.++## Verify the setup++The setup is complete when all of these checks pass:++- **Settings → Channels → Linear** shows the channel as on with no runtime error.+- While the channel is running, opening+ `http://127.0.0.1:3979/linear/health` on the nanobot machine returns+ `{"ok":true}`. Use your configured host and port if you changed them.+- A new comment with an explicit @mention creates an Agent Session and receives+ a response.+- A normal issue comment without an @mention does nothing.+- A follow-up inside the Agent Session receives a response without another+ @mention.++## Manual configuration++Use this path when deployment tooling manages `~/.nanobot/config.json` directly.+The WebUI path above is easier because it generates the Linear app definition+and completes OAuth for you.++Merge this section into `~/.nanobot/config.json`:++```json+{+ "channels": {+ "linear": {+ "enabled": true,+ "clientId": "YOUR_LINEAR_CLIENT_ID",+ "clientSecret": "YOUR_LINEAR_CLIENT_SECRET",+ "webhookSigningSecret": "YOUR_LINEAR_WEBHOOK_SIGNING_SECRET",+ "publicBaseUrl": "https://nanobot.example.com",+ "host": "127.0.0.1",+ "port": 3979,+ "webhookPath": "/linear/webhook",+ "oauthCallbackPath": "/linear/oauth/callback",+ "allowFrom": ["YOUR_LINEAR_USER_ID"]+ }+ }+}+```++Register these exact URLs in the Linear OAuth app:++```text+OAuth callback: https://nanobot.example.com/linear/oauth/callback+Webhook: https://nanobot.example.com/linear/webhook+```++Subscribe the webhook to exactly `AgentSessionEvent`, `PermissionChange`, and+`OAuthAuthorization`. Do not subscribe to `Comment`. The OAuth connection step+in the WebUI is still required: it installs the app and stores the+workspace-scoped access and refresh tokens.++## Security and reliability++- OAuth uses authorization code flow, PKCE, a short-lived CSRF state, and the+ Linear app actor.+- Webhooks are verified against `Linear-Signature` using the raw request body+ before JSON parsing. nanobot also checks the delivery timestamp and configured+ OAuth Client ID.+- `Linear-Delivery` IDs are deduplicated.+- Verified events are committed to a local SQLite queue before nanobot returns+ HTTP 200. Pending work resumes after a restart.+- Access and rotating refresh tokens are stored in the Linear channel state+ database, not in `config.json` or the browser.+- OAuth revocation removes the affected workspace installation locally.++Back up the nanobot instance data directory as carefully as other credentials.+Do not publish `linear/state.sqlite3`, the Client Secret, or the Webhook signing+secret.++## Troubleshooting++| Symptom | What to check |+|---|---|+| **Create prefilled Linear app** is missing | Enter only the public HTTPS origin in **Public HTTPS URL**, then select **Save settings**. |+| Linear rejects the callback or webhook URL | Use a stable public `https://` hostname. Do not use HTTP, localhost, a private IP, or a path in **Public HTTPS URL**. |+| OAuth opens but cannot finish | Keep `nanobot webui` running. Confirm the proxy forwards `/linear/oauth/callback` to the configured listen host and port. Then start **Connect Linear** again. |+| OAuth finishes in Linear but nanobot keeps waiting | The callback reached a different nanobot process or URL. Compare the app's Redirect URI with the callback URL shown by nanobot. |+| The local health URL does not load | Start **Connect Linear** or enable the connected channel, then check the configured listen host and port. |+| An @mention gets no response | Confirm `AgentSessionEvent` is subscribed, the Client ID and signing secret match the same app, and the workspace authorization has not been revoked. Run `nanobot gateway logs` for the exact error. |+| The first @mention returns a pairing code | Approve it in the WebUI pairing dialog, then repeat the prompt in the same Agent Session. Alternatively, configure a narrow **Allowed Linear users** list. |+| Normal comments do nothing | This is intentional. Start a task by @mentioning the app, or continue inside an existing Agent Session. |+| Issues can be delegated to the app without an @mention | Remove `app:assignable`, reconnect the workspace, and use nanobot's built-in OAuth flow, which requests only `read`, `write`, and `app:mentionable`. |+| Authorization reports missing scopes | Reconnect from nanobot. Do not reuse an authorization URL that omits `read`, `write`, or `app:mentionable`. |++For Linear's platform-side behavior, see the official+[Agents guide](https://linear.app/developers/agents),+[OAuth app manifest reference](https://linear.app/developers/oauth-app-manifests),+[OAuth guide](https://linear.app/developers/oauth-2-0-authentication), and+[webhook reference](https://linear.app/developers/webhooks).diff --git a/nanobot/channels/linear/__init__.py b/nanobot/channels/linear/__init__.pynew file mode 100644index 000000000..c921582fc--- /dev/null+++ b/nanobot/channels/linear/__init__.py@@ -0,0 +1 @@+"""Native Linear Agent channel."""diff --git a/nanobot/channels/linear/client.py b/nanobot/channels/linear/client.pynew file mode 100644index 000000000..543ac4498--- /dev/null+++ b/nanobot/channels/linear/client.py@@ -0,0 +1,324 @@+"""Minimal async Linear OAuth and GraphQL client."""++from __future__ import annotations++import asyncio+import time+from typing import Any, cast++import httpx++from nanobot.channels.linear.config import LinearConfig+from nanobot.channels.linear.oauth import LINEAR_SCOPES+from nanobot.channels.linear.state import LinearInstallation, LinearStateStore++LINEAR_GRAPHQL_URL = "https://api.linear.app/graphql"+LINEAR_TOKEN_URL = "https://api.linear.app/oauth/token"+++class LinearApiError(RuntimeError):+ """Linear returned a transport, authentication, or GraphQL error."""++ def __init__(+ self,+ message: str,+ *,+ retryable: bool = False,+ retry_after: float | None = None,+ ) -> None:+ super().__init__(message)+ self.retryable = retryable+ self.retry_after = retry_after+++class LinearClient:+ def __init__(+ self,+ config: LinearConfig,+ state: LinearStateStore,+ http: httpx.AsyncClient | None = None,+ ) -> None:+ self.config = config+ self.state = state+ self._http = http or httpx.AsyncClient(timeout=30.0)+ self._owns_http = http is None+ self._refresh_locks: dict[str, asyncio.Lock] = {}++ async def close(self) -> None:+ if self._owns_http:+ await self._http.aclose()++ async def exchange_code(self, code: str, verifier: str) -> LinearInstallation:+ token = await self._token_request(+ {+ "grant_type": "authorization_code",+ "code": code,+ "redirect_uri": self.config.redirect_uri,+ "client_id": self.config.client_id,+ "client_secret": self.config.client_secret,+ "code_verifier": verifier,+ }+ )+ access_token = _required_string(token, "access_token")+ identity = await self._graphql_with_token(+ access_token,+ "query NanobotLinearIdentity { viewer { id organization { id name } } }",+ {},+ )+ viewer = _required_mapping(identity, "viewer")+ organization = _required_mapping(viewer, "organization")+ scopes = _scopes(token.get("scope"))+ missing_scopes = set(LINEAR_SCOPES) - set(scopes)+ if missing_scopes:+ raise LinearApiError(+ "Linear authorization is missing required scope(s): "+ + ", ".join(sorted(missing_scopes))+ )+ installation = LinearInstallation(+ organization_id=_required_string(organization, "id"),+ oauth_client_id=self.config.client_id,+ organization_name=str(organization.get("name") or ""),+ app_user_id=_required_string(viewer, "id"),+ access_token=access_token,+ refresh_token=_required_string(token, "refresh_token"),+ expires_at=time.time() + _expires_in(token),+ scope=scopes,+ )+ self.state.save_installation(installation)+ return installation++ async def graphql(+ self,+ organization_id: str,+ query: str,+ variables: dict[str, Any],+ ) -> dict[str, Any]:+ installation = await self._fresh_installation(organization_id)+ try:+ return await self._graphql_with_token(installation.access_token, query, variables)+ except LinearApiError as exc:+ if "authentication" not in str(exc).lower():+ raise+ installation = await self._refresh(organization_id, force=True)+ return await self._graphql_with_token(installation.access_token, query, variables)++ async def create_activity(+ self,+ organization_id: str,+ agent_session_id: str,+ content: dict[str, Any],+ *,+ activity_id: str,+ ephemeral: bool = False,+ ) -> None:+ data = await self.graphql(+ organization_id,+ """+ mutation NanobotAgentActivityCreate($input: AgentActivityCreateInput!) {+ agentActivityCreate(input: $input) { success agentActivity { id } }+ }+ """,+ {+ "input": {+ "id": activity_id,+ "agentSessionId": agent_session_id,+ "content": content,+ "ephemeral": ephemeral,+ }+ },+ )+ result = _required_mapping(data, "agentActivityCreate")+ if result.get("success") is not True:+ raise LinearApiError("Linear did not accept the agent activity")++ async def _fresh_installation(self, organization_id: str) -> LinearInstallation:+ installation = self.state.installation(organization_id)+ if installation is None:+ raise LinearApiError(+ f"No Linear OAuth installation for organization {organization_id}"+ )+ if installation.oauth_client_id != self.config.client_id:+ raise LinearApiError(+ "The Linear workspace was authorized for a different OAuth Client ID; reconnect it"+ )+ if installation.expires_at <= time.time() + 60:+ return await self._refresh(organization_id)+ return installation++ async def _refresh(self, organization_id: str, *, force: bool = False) -> LinearInstallation:+ lock = self._refresh_locks.setdefault(organization_id, asyncio.Lock())+ async with lock:+ installation = self.state.installation(organization_id)+ if installation is None:+ raise LinearApiError(+ f"No Linear OAuth installation for organization {organization_id}"+ )+ if not force and installation.expires_at > time.time() + 60:+ return installation+ token = await self._token_request(+ {+ "grant_type": "refresh_token",+ "refresh_token": installation.refresh_token,+ "client_id": self.config.client_id,+ "client_secret": self.config.client_secret,+ }+ )+ refreshed = LinearInstallation(+ organization_id=installation.organization_id,+ oauth_client_id=installation.oauth_client_id,+ organization_name=installation.organization_name,+ app_user_id=installation.app_user_id,+ access_token=_required_string(token, "access_token"),+ refresh_token=_required_string(token, "refresh_token"),+ expires_at=time.time() + _expires_in(token),+ scope=_scopes(token.get("scope")) or installation.scope,+ )+ missing_scopes = set(LINEAR_SCOPES) - set(refreshed.scope)+ if missing_scopes:+ raise LinearApiError(+ "Refreshed Linear authorization is missing required scope(s): "+ + ", ".join(sorted(missing_scopes))+ )+ self.state.save_installation(refreshed)+ return refreshed++ async def _token_request(self, form: dict[str, str]) -> dict[str, Any]:+ try:+ response = await self._http.post(LINEAR_TOKEN_URL, data=form)+ except httpx.HTTPError as exc:+ raise LinearApiError(f"Linear OAuth request failed: {exc}", retryable=True) from exc+ payload = _response_object(response)+ if response.is_error:+ detail = str(payload.get("error_description") or payload.get("error") or response.status_code)+ raise LinearApiError(+ f"Linear OAuth request failed: {detail}",+ retryable=response.status_code == 429 or response.status_code >= 500,+ retry_after=_retry_after_seconds(response),+ )+ return payload++ async def _graphql_with_token(+ self,+ access_token: str,+ query: str,+ variables: dict[str, Any],+ ) -> dict[str, Any]:+ try:+ response = await self._http.post(+ LINEAR_GRAPHQL_URL,+ headers={"Authorization": f"Bearer {access_token}"},+ json={"query": query, "variables": variables},+ )+ except httpx.HTTPError as exc:+ raise LinearApiError(f"Linear API request failed: {exc}", retryable=True) from exc+ if response.status_code in {401, 403}:+ raise LinearApiError("Linear authentication failed")+ payload = _response_object(response)+ errors = payload.get("errors")+ if isinstance(errors, list) and errors:+ messages: list[str] = []+ retryable = False+ for raw_error in cast(list[object], errors):+ if isinstance(raw_error, dict):+ error = cast(dict[str, Any], raw_error)+ message = str(error.get("message") or "GraphQL error")+ messages.append(message)+ extensions = error.get("extensions")+ code = (+ str(cast(dict[str, Any], extensions).get("code") or "").upper()+ if isinstance(extensions, dict)+ else ""+ )+ retryable = retryable or code in {+ "INTERNAL_ERROR",+ "INTERNAL_SERVER_ERROR",+ "RATELIMITED",+ "SERVICE_UNAVAILABLE",+ } or "internal" in message.lower()+ message = "; ".join(messages) or "GraphQL error"+ raise LinearApiError(+ message,+ retryable=retryable,+ retry_after=_retry_after_seconds(response) if retryable else None,+ )+ if response.is_error:+ raise LinearApiError(+ f"Linear API request failed with HTTP {response.status_code}",+ retryable=response.status_code == 429 or response.status_code >= 500,+ retry_after=_retry_after_seconds(response),+ )+ data = payload.get("data")+ if not isinstance(data, dict):+ raise LinearApiError("Linear API response did not contain data")+ return cast(dict[str, Any], data)+++def _response_object(response: httpx.Response) -> dict[str, Any]:+ retryable = response.status_code == 429 or response.status_code >= 500+ try:+ value: object = response.json()+ except ValueError as exc:+ raise LinearApiError(+ "Linear returned a non-JSON response",+ retryable=retryable,+ retry_after=_retry_after_seconds(response) if retryable else None,+ ) from exc+ if not isinstance(value, dict):+ raise LinearApiError(+ "Linear returned an invalid JSON response",+ retryable=retryable,+ retry_after=_retry_after_seconds(response) if retryable else None,+ )+ return cast(dict[str, Any], value)+++def _retry_after_seconds(response: httpx.Response) -> float | None:+ raw_retry_after = response.headers.get("Retry-After", "").strip()+ try:+ retry_after = float(raw_retry_after)+ except ValueError:+ retry_after = -1.0+ if retry_after >= 0:+ return retry_after+ for header in (+ "X-RateLimit-Endpoint-Requests-Reset",+ "X-RateLimit-Requests-Reset",+ "X-RateLimit-Complexity-Reset",+ ):+ raw_reset = response.headers.get(header, "").strip()+ try:+ reset = float(raw_reset)+ except ValueError:+ continue+ reset_seconds = reset / 1000 if reset > 10_000_000_000 else reset+ return max(0.0, reset_seconds - time.time())+ return None+++def _required_mapping(value: dict[str, Any], key: str) -> dict[str, Any]:+ item = value.get(key)+ if not isinstance(item, dict):+ raise LinearApiError(f"Linear response is missing {key}")+ return cast(dict[str, Any], item)+++def _required_string(value: dict[str, Any], key: str) -> str:+ item = value.get(key)+ if not isinstance(item, str) or not item:+ raise LinearApiError(f"Linear response is missing {key}")+ return item+++def _expires_in(value: dict[str, Any]) -> float:+ expires = value.get("expires_in")+ if isinstance(expires, int | float) and not isinstance(expires, bool):+ return max(60.0, float(expires))+ return 86400.0+++def _scopes(value: object) -> tuple[str, ...]:+ if isinstance(value, str):+ return tuple(item for item in value.replace(",", " ").split() if item)+ if isinstance(value, list):+ return tuple(str(item) for item in cast(list[object], value))+ return ()diff --git a/nanobot/channels/linear/config.py b/nanobot/channels/linear/config.pynew file mode 100644index 000000000..809ffb59e--- /dev/null+++ b/nanobot/channels/linear/config.py@@ -0,0 +1,100 @@+"""Configuration and URL validation for the native Linear channel."""++from __future__ import annotations++import ipaddress+from urllib.parse import urlparse++from pydantic import Field, field_validator, model_validator++from nanobot.config_base import Base++DEFAULT_PORT = 3979+DEFAULT_WEBHOOK_PATH = "/linear/webhook"+DEFAULT_OAUTH_CALLBACK_PATH = "/linear/oauth/callback"+++class LinearConfig(Base):+ """Linear OAuth app and local webhook listener settings."""++ enabled: bool = False+ client_id: str = ""+ client_secret: str = ""+ webhook_signing_secret: str = ""+ public_base_url: str = ""+ host: str = "0.0.0.0"+ port: int = Field(default=DEFAULT_PORT, ge=1, le=65535)+ webhook_path: str = DEFAULT_WEBHOOK_PATH+ oauth_callback_path: str = DEFAULT_OAUTH_CALLBACK_PATH+ allow_from: list[str] = Field(default_factory=list)+ send_progress: bool = True+ send_tool_hints: bool = True+ show_reasoning: bool = True++ @field_validator("webhook_path", "oauth_callback_path")+ @classmethod+ def validate_path(cls, value: str) -> str:+ path = value.strip()+ if not path.startswith("/") or "?" in path or "#" in path:+ raise ValueError("must be an absolute URL path without a query or fragment")+ return path.rstrip("/") or "/"++ @field_validator("public_base_url")+ @classmethod+ def normalize_public_base_url(cls, value: str) -> str:+ raw = value.strip()+ return validate_public_base_url(raw) if raw else ""++ @model_validator(mode="after")+ def validate_distinct_paths(self) -> LinearConfig:+ if self.webhook_path == self.oauth_callback_path:+ raise ValueError("Linear webhookPath and oauthCallbackPath must be different")+ return self++ def validate_runtime(self) -> None:+ missing = [+ label+ for label, value in (+ ("clientId", self.client_id),+ ("clientSecret", self.client_secret),+ ("webhookSigningSecret", self.webhook_signing_secret),+ ("publicBaseUrl", self.public_base_url),+ )+ if not value.strip()+ ]+ if missing:+ raise ValueError("Missing Linear setting(s): " + ", ".join(missing))++ @property+ def redirect_uri(self) -> str:+ return self.public_base_url.rstrip("/") + self.oauth_callback_path++ @property+ def webhook_url(self) -> str:+ return self.public_base_url.rstrip("/") + self.webhook_path+++def validate_public_base_url(value: str) -> str:+ """Require the externally reachable HTTPS origin Linear expects."""+ raw = value.strip()+ parsed = urlparse(raw)+ if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password:+ raise ValueError("publicBaseUrl must be an HTTPS origin, for example https://bot.example.com")+ if parsed.path not in {"", "/"} or parsed.query or parsed.fragment:+ raise ValueError("publicBaseUrl must not include a path, query, or fragment")+ try:+ parsed.port+ except ValueError as exc:+ raise ValueError("publicBaseUrl contains an invalid port") from exc+ if parsed.netloc.endswith(":") or any(character.isspace() for character in parsed.netloc):+ raise ValueError("publicBaseUrl contains an invalid host or port")+ host = parsed.hostname.lower()+ if host == "localhost" or host.endswith(".localhost"):+ raise ValueError("publicBaseUrl must be public; localhost is not accepted by Linear")+ try:+ address = ipaddress.ip_address(host)+ except ValueError:+ address = None+ if address is not None and not address.is_global:+ raise ValueError("publicBaseUrl must not use a private or loopback IP address")+ return raw.rstrip("/")diff --git a/nanobot/channels/linear/connect.py b/nanobot/channels/linear/connect.pynew file mode 100644index 000000000..8029aedc1--- /dev/null+++ b/nanobot/channels/linear/connect.py@@ -0,0 +1,175 @@+"""WebUI OAuth connection flow for Linear workspace installations."""++from __future__ import annotations++import asyncio+import time+from dataclasses import dataclass, field+from typing import Any, cast++from nanobot.channels.connect import ChannelConnectError, QueryParams, query_first+from nanobot.channels.linear.client import LinearApiError, LinearClient+from nanobot.channels.linear.config import LinearConfig+from nanobot.channels.linear.oauth import (+ FLOW_TTL_SECONDS,+ OAUTH_FLOWS,+ LinearOAuthFlow,+ authorization_url,+)+from nanobot.channels.linear.server import LinearServerLease, acquire_http_server+from nanobot.channels.linear.state import LinearStateStore+from nanobot.config.loader import load_config+++@dataclass(slots=True)+class LinearConnectSession:+ flow: LinearOAuthFlow+ config: LinearConfig+ state: LinearStateStore+ server: LinearServerLease+ completion_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)+++class LinearConnectStore:+ """Keep short-lived OAuth browser sessions in the gateway process."""++ def __init__(self) -> None:+ self._sessions: dict[str, LinearConnectSession] = {}++ async def handle(self, action: str, query: QueryParams) -> dict[str, Any]:+ await self._cleanup()+ if action == "start":+ return await self.start(force=_query_bool(query, "force"))+ session_id = (query_first(query, "session_id") or "").strip()+ if not session_id:+ raise ChannelConnectError("missing Linear connect session")+ if action == "poll":+ return await self.poll(session_id)+ if action == "cancel":+ return await self.cancel(session_id)+ raise ChannelConnectError(f"unsupported Linear connect action: {action}", status=404)++ async def start(self, *, force: bool = False) -> dict[str, Any]:+ config = _load_linear_config()+ try:+ config.validate_runtime()+ except ValueError as exc:+ raise ChannelConnectError(str(exc)) from exc+ state = LinearStateStore()+ if state.has_installations(config.client_id) and not force:+ return {+ "session_id": "",+ "status": "succeeded",+ "message": "Linear is already connected. Use reconnect to add or replace a workspace.",+ }+ flow = OAUTH_FLOWS.create()+ try:+ lease = await asyncio.to_thread(acquire_http_server, config, state)+ except (OSError, RuntimeError) as exc:+ OAUTH_FLOWS.remove(flow)+ raise ChannelConnectError(+ f"Unable to start the Linear callback listener on {config.host}:{config.port}: {exc}",+ status=502,+ ) from exc+ self._sessions[flow.session_id] = LinearConnectSession(+ flow=flow,+ config=config,+ state=state,+ server=lease,+ )+ return {+ "session_id": flow.session_id,+ "status": "pending",+ "authorization_url": authorization_url(config, flow),+ "qr_url": authorization_url(config, flow),+ "redirect_uri": config.redirect_uri,+ "webhook_url": config.webhook_url,+ "interval_ms": 1500,+ "expires_at_ms": int((flow.created_at + FLOW_TTL_SECONDS) * 1000),+ "message": "Authorize the nanobot app in Linear.",+ }++ async def poll(self, session_id: str) -> dict[str, Any]:+ session = self._sessions.get(session_id)+ if session is None:+ return _terminal(session_id, "expired", "This Linear authorization has expired.")+ async with session.completion_lock:+ if self._sessions.get(session_id) is not session:+ return _terminal(session_id, "cancelled", "Linear authorization cancelled.")+ flow = session.flow+ if time.monotonic() >= flow.deadline:+ await self._close_session(session_id)+ return _terminal(session_id, "expired", "This Linear authorization has expired.")+ if flow.error:+ message = "Linear authorization was cancelled."+ await self._close_session(session_id)+ return _terminal(session_id, "failed", message)+ if not flow.code:+ return {+ "session_id": session_id,+ "status": "pending",+ "interval_ms": 1500,+ "expires_at_ms": int((flow.created_at + FLOW_TTL_SECONDS) * 1000),+ "message": "Waiting for Linear authorization.",+ }++ client = LinearClient(session.config, session.state)+ try:+ installation = await client.exchange_code(flow.code, flow.verifier)+ except LinearApiError as exc:+ await self._close_session(session_id)+ return _terminal(+ session_id,+ "failed",+ f"Linear authorization could not be completed: {exc}",+ )+ finally:+ await client.close()+ await self._close_session(session_id)+ return {+ "session_id": session_id,+ "status": "succeeded",+ "message": "Linear is connected.",+ "organization_id": installation.organization_id,+ "organization_name": installation.organization_name,+ }++ async def cancel(self, session_id: str) -> dict[str, Any]:+ session = self._sessions.get(session_id)+ if session is not None:+ async with session.completion_lock:+ await self._close_session(session_id)+ return _terminal(session_id, "cancelled", "Linear authorization cancelled.")++ async def _cleanup(self) -> None:+ expired = [+ session_id+ for session_id, session in self._sessions.items()+ if time.monotonic() >= session.flow.deadline+ ]+ for session_id in expired:+ await self.cancel(session_id)++ async def _close_session(self, session_id: str) -> None:+ session = self._sessions.pop(session_id, None)+ if session is None:+ return+ OAUTH_FLOWS.remove(session.flow)+ await asyncio.to_thread(session.server.close)+++def _load_linear_config() -> LinearConfig:+ config = load_config()+ extras: dict[str, Any] = config.channels.model_extra or {}+ raw: object = extras.get("linear", {})+ if not isinstance(raw, dict):+ raw = {}+ return LinearConfig.model_validate(cast(dict[str, Any], raw))+++def _query_bool(query: QueryParams, key: str) -> bool:+ return (query_first(query, key) or "").strip().lower() in {"1", "true", "yes"}+++def _terminal(session_id: str, status: str, message: str) -> dict[str, Any]:+ return {"session_id": session_id, "status": status, "message": message}diff --git a/nanobot/channels/linear/manifest.py b/nanobot/channels/linear/manifest.pynew file mode 100644index 000000000..066f73ee2--- /dev/null+++ b/nanobot/channels/linear/manifest.py@@ -0,0 +1,38 @@+"""Dependency-free management contract for the native Linear Agent channel."""++from nanobot.channels._manifest import field, required_fields+from nanobot.channels.contracts import ChannelManagementSpec, ChannelSetupSpec+from nanobot.channels.linear.state import local_state_present+from nanobot.channels.linear.validation import validate+from nanobot.channels.plugin import ChannelPlugin++SETUP_SPEC = ChannelSetupSpec(+ fields={+ "clientId": field(),+ "clientSecret": field("secret"),+ "webhookSigningSecret": field("secret"),+ "publicBaseUrl": field(),+ "host": field(default="0.0.0.0"),+ "port": field("int", default=3979),+ "webhookPath": field(default="/linear/webhook"),+ "oauthCallbackPath": field(default="/linear/oauth/callback"),+ "allowFrom": field("list"),+ },+ required=required_fields(+ "clientId",+ "clientSecret",+ "webhookSigningSecret",+ "publicBaseUrl",+ ),+ validator=validate,+)++PLUGIN = ChannelPlugin(+ name="linear",+ display_name="Linear",+ runtime=f"{__package__}.runtime:LinearChannel",+ connector=f"{__package__}.connect:LinearConnectStore",+ setup=SETUP_SPEC,+ management=ChannelManagementSpec(local_state_present=local_state_present),+ webui="webui/index.tsx",+)diff --git a/nanobot/channels/linear/oauth.py b/nanobot/channels/linear/oauth.pynew file mode 100644index 000000000..d54e3e33b--- /dev/null+++ b/nanobot/channels/linear/oauth.py@@ -0,0 +1,92 @@+"""PKCE OAuth flow state for Linear app installations."""++from __future__ import annotations++import base64+import hashlib+import secrets+import threading+import time+from dataclasses import dataclass+from urllib.parse import urlencode++from nanobot.channels.linear.config import LinearConfig++LINEAR_AUTHORIZE_URL = "https://linear.app/oauth/authorize"+LINEAR_SCOPES = ("read", "write", "app:mentionable")+FLOW_TTL_SECONDS = 600+++@dataclass(slots=True)+class LinearOAuthFlow:+ session_id: str+ state: str+ verifier: str+ created_at: float+ deadline: float+ code: str | None = None+ error: str | None = None+++class LinearOAuthFlows:+ """Process-local, short-lived OAuth state shared with the callback server."""++ def __init__(self) -> None:+ self._guard = threading.RLock()+ self._by_state: dict[str, LinearOAuthFlow] = {}++ def create(self) -> LinearOAuthFlow:+ now = time.monotonic()+ flow = LinearOAuthFlow(+ session_id=secrets.token_urlsafe(18),+ state=secrets.token_urlsafe(32),+ verifier=secrets.token_urlsafe(64),+ created_at=time.time(),+ deadline=now + FLOW_TTL_SECONDS,+ )+ with self._guard:+ self._cleanup_locked(now)+ self._by_state[flow.state] = flow+ return flow++ def complete(self, state: str, *, code: str | None, error: str | None) -> bool:+ with self._guard:+ self._cleanup_locked(time.monotonic())+ flow = self._by_state.get(state)+ if flow is None or flow.code is not None or flow.error is not None:+ return False+ flow.code = code+ flow.error = error+ return True++ def remove(self, flow: LinearOAuthFlow) -> None:+ with self._guard:+ if self._by_state.get(flow.state) is flow:+ self._by_state.pop(flow.state, None)++ def _cleanup_locked(self, now: float) -> None:+ expired = [state for state, flow in self._by_state.items() if now >= flow.deadline]+ for state in expired:+ self._by_state.pop(state, None)+++OAUTH_FLOWS = LinearOAuthFlows()+++def authorization_url(config: LinearConfig, flow: LinearOAuthFlow) -> str:+ digest = hashlib.sha256(flow.verifier.encode()).digest()+ challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()+ query = urlencode(+ {+ "client_id": config.client_id,+ "redirect_uri": config.redirect_uri,+ "response_type": "code",+ "scope": ",".join(LINEAR_SCOPES),+ "actor": "app",+ "prompt": "consent",+ "state": flow.state,+ "code_challenge": challenge,+ "code_challenge_method": "S256",+ }+ )+ return f"{LINEAR_AUTHORIZE_URL}?{query}"diff --git a/nanobot/channels/linear/runtime.py b/nanobot/channels/linear/runtime.pynew file mode 100644index 000000000..0f90a73c7--- /dev/null+++ b/nanobot/channels/linear/runtime.py@@ -0,0 +1,400 @@+"""Native Linear Agent channel runtime."""++from __future__ import annotations++import asyncio+import json+import uuid+from contextlib import suppress+from typing import Any, cast++from nanobot.bus.events import OutboundMessage+from nanobot.bus.outbound_events import ProgressEvent, RetryWaitEvent, outbound_event_from_message+from nanobot.bus.queue import MessageBus+from nanobot.channels.base import BaseChannel+from nanobot.channels.linear.client import LinearApiError, LinearClient+from nanobot.channels.linear.config import LinearConfig+from nanobot.channels.linear.server import LinearServerLease, acquire_http_server+from nanobot.channels.linear.state import LinearStateStore, QueuedWebhook+++class LinearPayloadError(ValueError):+ """A signed webhook has an unsupported or malformed payload."""+++class LinearChannel(BaseChannel):+ """Receive @mention Agent Sessions and publish native Agent Activities."""++ name = "linear"+ display_name = "Linear"++ @classmethod+ def default_config(cls) -> dict[str, Any]:+ return LinearConfig().model_dump(mode="json", by_alias=True)++ def __init__(self, config: Any, bus: MessageBus):+ if isinstance(config, dict):+ config = LinearConfig.model_validate(config)+ super().__init__(config, bus)+ self.config: LinearConfig = config+ self._state = LinearStateStore()+ self._client: LinearClient | None = None+ self._server: LinearServerLease | None = None+ self._reasoning: dict[tuple[str, str], list[str]] = {}+ self._routes: dict[str, dict[str, Any]] = {}++ def progress_transport_defaults(self) -> tuple[bool, bool] | None:+ return self.config.send_progress, self.config.send_tool_hints++ async def start(self) -> None:+ self.config.validate_runtime()+ if not self._state.has_installations(self.config.client_id):+ raise RuntimeError("Connect at least one Linear workspace with OAuth before enabling")+ self._state.recover_processing_webhooks()+ self._client = LinearClient(self.config, self._state)+ try:+ self._server = await asyncio.to_thread(+ acquire_http_server,+ self.config,+ self._state,+ )+ except Exception:+ await self._client.close()+ self._client = None+ raise+ self._running = True+ self.logger.info(+ "Linear webhook listening on http://{}:{}{} (public URL: {})",+ self.config.host,+ self.config.port,+ self.config.webhook_path,+ self.config.webhook_url,+ )+ while self._running:+ events = await asyncio.to_thread(self._state.claim_webhooks)+ if not events:+ await asyncio.sleep(0.2)+ continue+ for event in events:+ await self._process_queued_webhook(event)++ async def stop(self) -> None:+ self._running = False+ if self._server is not None:+ await asyncio.to_thread(self._server.close)+ self._server = None+ if self._client is not None:+ await self._client.close()+ self._client = None+ self._reasoning.clear()+ self._routes.clear()++ def start_error_message(self, error: Exception) -> str | None:+ return f"Linear channel failed to start: {error}"++ async def send(self, msg: OutboundMessage) -> None:+ event = outbound_event_from_message(msg)+ if isinstance(event, ProgressEvent):+ if event.tool_events:+ for item in event.tool_events:+ await self._send_tool_event(msg, item)+ return+ if msg.content:+ await self._create_activity(+ msg.chat_id,+ msg.metadata,+ {"type": "thought", "body": msg.content},+ key=f"progress:{hash(msg.content)}",+ ephemeral=True,+ )+ return+ if isinstance(event, RetryWaitEvent):+ await self._create_activity(+ msg.chat_id,+ msg.metadata,+ {"type": "thought", "body": msg.content},+ key=f"retry:{hash(msg.content)}",+ ephemeral=True,+ )+ return+ if not msg.content:+ return+ await self._create_activity(+ msg.chat_id,+ msg.metadata,+ {"type": "response", "body": msg.content},+ key="response",+ )++ async def send_reasoning_delta(+ self,+ chat_id: str,+ delta: str,+ metadata: dict[str, Any] | None = None,+ *,+ stream_id: str | None = None,+ ) -> None:+ key = (chat_id, stream_id or "default")+ self._reasoning.setdefault(key, []).append(delta)++ async def send_reasoning_end(+ self,+ chat_id: str,+ metadata: dict[str, Any] | None = None,+ *,+ stream_id: str | None = None,+ ) -> None:+ key = (chat_id, stream_id or "default")+ body = "".join(self._reasoning.pop(key, [])).strip()+ if body:+ await self._create_activity(+ chat_id,+ metadata or {},+ {"type": "thought", "body": body},+ key=f"reasoning:{stream_id or 'default'}",+ )++ async def send_file_edit_events(+ self,+ chat_id: str,+ edits: list[dict[str, Any]],+ metadata: dict[str, Any] | None = None,+ ) -> None:+ for index, edit in enumerate(edits):+ path = str(edit.get("path") or edit.get("file") or "file")+ result = str(edit.get("status") or edit.get("phase") or "updated")+ await self._create_activity(+ chat_id,+ metadata or {},+ {+ "type": "action",+ "action": "Edit file",+ "parameter": path,+ "result": result,+ },+ key=f"file:{path}:{index}:{result}",+ )++ async def _send_tool_event(self, msg: OutboundMessage, item: dict[str, Any]) -> None:+ name = str(item.get("name") or "tool")+ phase = str(item.get("phase") or "start")+ call_id = str(item.get("call_id") or uuid.uuid4())+ arguments = item.get("arguments")+ parameter = json.dumps(arguments, ensure_ascii=False, default=str)[:2000]+ content: dict[str, Any] = {+ "type": "action",+ "action": name,+ "parameter": parameter,+ }+ if phase == "end":+ content["result"] = _compact_result(item.get("result"))+ elif phase == "error":+ content["result"] = str(item.get("error") or "Tool execution failed")+ await self._create_activity(+ msg.chat_id,+ msg.metadata,+ content,+ key=f"tool:{call_id}:{phase}",+ )++ async def _create_activity(+ self,+ chat_id: str,+ metadata: dict[str, Any],+ content: dict[str, Any],+ *,+ key: str,+ ephemeral: bool = False,+ ) -> None:+ client = self._client+ if client is None:+ raise RuntimeError("Linear HTTP client is not initialized")+ route = _linear_route(metadata) or self._routes.get(chat_id)+ if route is None:+ raise RuntimeError("Linear outbound message is missing route metadata")+ metadata.setdefault("linear", route)+ session_id = str(route.get("agent_session_id") or chat_id)+ organization_id = _required_text(route, "organization_id")+ activity_ids_raw = metadata.setdefault("_linear_activity_ids", {})+ if not isinstance(activity_ids_raw, dict):+ activity_ids_raw = {}+ metadata["_linear_activity_ids"] = activity_ids_raw+ activity_ids = cast(dict[str, Any], activity_ids_raw)+ activity_id = str(activity_ids.setdefault(key, str(uuid.uuid4())))+ await client.create_activity(+ organization_id,+ session_id,+ content,+ activity_id=activity_id,+ ephemeral=ephemeral,+ )++ async def _process_queued_webhook(self, event: QueuedWebhook) -> None:+ try:+ await self._process_webhook(event.delivery_id, event.payload)+ except LinearPayloadError as exc:+ self.logger.warning("Dropping invalid Linear webhook {}: {}", event.delivery_id, exc)+ await asyncio.to_thread(self._state.complete_webhook, event.delivery_id)+ except LinearApiError as exc:+ self.logger.warning("Linear webhook {} failed: {}", event.delivery_id, exc)+ if exc.retryable:+ await asyncio.to_thread(+ self._state.retry_webhook,+ event.delivery_id,+ str(exc),+ event.attempts,+ exc.retry_after,+ )+ else:+ await asyncio.to_thread(self._state.complete_webhook, event.delivery_id)+ except Exception as exc:+ self.logger.exception("Linear webhook {} failed", event.delivery_id)+ await asyncio.to_thread(+ self._state.retry_webhook,+ event.delivery_id,+ str(exc),+ event.attempts,+ )+ else:+ await asyncio.to_thread(self._state.complete_webhook, event.delivery_id)++ async def _process_webhook(self, delivery_id: str, payload: dict[str, Any]) -> None:+ event_type = payload.get("type")+ if event_type in {"OAuthApp", "OAuthAuthorization", "PermissionChange"}:+ self._process_lifecycle_event(payload)+ return+ if event_type != "AgentSessionEvent":+ raise LinearPayloadError("unsupported event type")+ action = _required_text(payload, "action")+ if action not in {"created", "prompted"}:+ return+ session = _required_object(payload, "agentSession")+ agent_session_id = _required_text(session, "id")+ organization_id = _required_text(payload, "organizationId")+ if str(session.get("organizationId") or organization_id) != organization_id:+ raise LinearPayloadError("organization mismatch")+ installation = self._state.installation(organization_id)+ if installation is None:+ raise LinearPayloadError("organization is not installed")+ activity = _optional_object(payload.get("agentActivity"))+ if activity and str(activity.get("userId") or "") == installation.app_user_id:+ return+ signal = str(activity.get("signal") or "") if activity else ""+ sender_id = str(+ (activity or {}).get("userId")+ or session.get("creatorId")+ or ""+ ).strip()+ if not sender_id:+ raise LinearPayloadError("missing sender identity")+ content = "/stop" if signal == "stop" else _prompt_text(payload, session, activity, action)+ if not content:+ if signal in {"auth", "continue", "select"}:+ content = _signal_text(signal, activity)+ if not content:+ return+ metadata = {+ "message_id": delivery_id,+ "linear": {+ "organization_id": organization_id,+ "agent_session_id": agent_session_id,+ "issue_id": str(session.get("issueId") or ""),+ "comment_id": str(session.get("commentId") or ""),+ "app_user_id": installation.app_user_id,+ "oauth_client_id": str(payload.get("oauthClientId") or ""),+ "action": action,+ "signal": signal,+ "delivery_id": delivery_id,+ },+ }+ self._routes[agent_session_id] = cast(dict[str, Any], metadata["linear"])+ if len(self._routes) > 1000:+ self._routes.pop(next(iter(self._routes)))+ await self._create_activity(+ agent_session_id,+ metadata,+ {"type": "thought", "body": "Starting…"},+ key="accepted",+ ephemeral=True,+ )+ await self._handle_message(+ sender_id=sender_id,+ chat_id=agent_session_id,+ content=content,+ metadata=metadata,+ session_key=f"linear:{organization_id}:{agent_session_id}",+ is_dm=True,+ )++ def _process_lifecycle_event(self, payload: dict[str, Any]) -> None:+ action = str(payload.get("action") or "").lower()+ organization_id = str(payload.get("organizationId") or "").strip()+ if organization_id and action in {"remove", "removed", "revoke", "revoked"}:+ self._state.delete_installation(organization_id)+ self.logger.info("Removed revoked Linear workspace installation {}", organization_id)+++def _linear_route(metadata: dict[str, Any]) -> dict[str, Any] | None:+ value = metadata.get("linear")+ return cast(dict[str, Any], value) if isinstance(value, dict) else None+++def _required_text(value: dict[str, Any], key: str) -> str:+ item = value.get(key)+ if not isinstance(item, str) or not item.strip():+ raise LinearPayloadError(f"missing {key}")+ return item.strip()+++def _required_object(value: dict[str, Any], key: str) -> dict[str, Any]:+ item = value.get(key)+ if not isinstance(item, dict):+ raise LinearPayloadError(f"missing {key}")+ return cast(dict[str, Any], item)+++def _optional_object(value: object) -> dict[str, Any]:+ return cast(dict[str, Any], value) if isinstance(value, dict) else {}+++def _prompt_text(+ payload: dict[str, Any],+ session: dict[str, Any],+ activity: dict[str, Any],+ action: str,+) -> str:+ value: object+ if action == "created":+ value = payload.get("promptContext")+ else:+ value = activity.get("body") or activity.get("content")+ return _text_from_value(value) or _text_from_value(session.get("comment"))+++def _text_from_value(value: object) -> str:+ if isinstance(value, str):+ return value.strip()+ if isinstance(value, dict):+ mapping = cast(dict[str, Any], value)+ for key in ("body", "text", "prompt", "content"):+ text = _text_from_value(mapping.get(key))+ if text:+ return text+ if isinstance(value, list):+ parts = [_text_from_value(item) for item in cast(list[object], value)]+ return "\n".join(part for part in parts if part)+ return ""+++def _signal_text(signal: str, activity: dict[str, Any]) -> str:+ metadata = activity.get("signalMetadata")+ text = _text_from_value(metadata)+ return text or f"Linear agent signal: {signal}"+++def _compact_result(value: object) -> str:+ if isinstance(value, str):+ return value[:2000]+ with suppress(TypeError, ValueError):+ return json.dumps(value, ensure_ascii=False, default=str)[:2000]+ return str(value)[:2000]diff --git a/nanobot/channels/linear/server.py b/nanobot/channels/linear/server.pynew file mode 100644index 000000000..9e00608e9--- /dev/null+++ b/nanobot/channels/linear/server.py@@ -0,0 +1,282 @@+"""Shared local HTTP listener for Linear webhooks and OAuth callbacks."""++from __future__ import annotations++import hashlib+import hmac+import json+import threading+import time+from datetime import datetime+from http import HTTPStatus+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer+from typing import Any, cast+from urllib.parse import parse_qs, urlparse++from loguru import logger++from nanobot.channels.linear.config import LinearConfig+from nanobot.channels.linear.oauth import OAUTH_FLOWS+from nanobot.channels.linear.state import LinearStateStore++MAX_WEBHOOK_BYTES = 1024 * 1024+MAX_WEBHOOK_AGE_SECONDS = 60+WEBHOOK_TYPES = {+ "AgentSessionEvent",+ "OAuthApp",+ "OAuthAuthorization",+ "PermissionChange",+}+++class LinearWebhookError(ValueError):+ def __init__(self, message: str, status: HTTPStatus = HTTPStatus.BAD_REQUEST) -> None:+ super().__init__(message)+ self.status = status+++class _ReusableThreadingHTTPServer(ThreadingHTTPServer):+ allow_reuse_address = True+ daemon_threads = True+++class SharedLinearHttpServer:+ def __init__(self, config: LinearConfig, state: LinearStateStore) -> None:+ self.config = config+ self.state = state+ self._references = 0+ self._server: ThreadingHTTPServer | None = None+ self._thread: threading.Thread | None = None++ @property+ def identity(self) -> tuple[str, int, str, str, str, str]:+ return (+ self.config.host,+ self.config.port,+ self.config.client_id,+ self.config.webhook_signing_secret,+ self.config.webhook_path,+ self.config.oauth_callback_path,+ )++ def start(self) -> None:+ owner = self++ class Handler(BaseHTTPRequestHandler):+ protocol_version = "HTTP/1.1"++ def do_GET(self) -> None: # noqa: N802+ parsed = urlparse(self.path)+ if parsed.path == owner.config.oauth_callback_path:+ owner._handle_oauth_callback(self, parse_qs(parsed.query))+ return+ if parsed.path == "/linear/health":+ self._send(HTTPStatus.OK, b'{"ok":true}', "application/json")+ return+ self._send(HTTPStatus.NOT_FOUND, b"not found", "text/plain; charset=utf-8")++ def do_POST(self) -> None: # noqa: N802+ parsed = urlparse(self.path)+ if parsed.path != owner.config.webhook_path:+ self._send(HTTPStatus.NOT_FOUND, b"not found", "text/plain; charset=utf-8")+ return+ try:+ owner._handle_webhook(self)+ except LinearWebhookError as exc:+ logger.bind(channel="linear").warning("Rejected Linear webhook: {}", exc)+ self._send(exc.status, str(exc).encode(), "text/plain; charset=utf-8")+ except Exception:+ logger.bind(channel="linear").exception(+ "Could not persist a verified Linear webhook"+ )+ self._send(+ HTTPStatus.INTERNAL_SERVER_ERROR,+ b"webhook persistence failed",+ "text/plain; charset=utf-8",+ )++ def _send(self, status: HTTPStatus, body: bytes, content_type: str) -> None:+ self.send_response(status.value)+ self.send_header("Content-Type", content_type)+ self.send_header("Content-Length", str(len(body)))+ self.send_header("Cache-Control", "no-store")+ self.send_header("X-Content-Type-Options", "nosniff")+ self.end_headers()+ self.wfile.write(body)++ def log_message(self, format: str, *args: Any) -> None:+ return++ self._server = _ReusableThreadingHTTPServer(+ (self.config.host, self.config.port),+ Handler,+ )+ self._thread = threading.Thread(+ target=self._server.serve_forever,+ name="nanobot-linear",+ daemon=True,+ )+ self._thread.start()++ def close(self) -> None:+ if self._server is not None:+ self._server.shutdown()+ self._server.server_close()+ self._server = None+ if self._thread is not None and self._thread.is_alive():+ self._thread.join(timeout=2)+ self._thread = None++ def _handle_oauth_callback(+ self,+ handler: BaseHTTPRequestHandler,+ query: dict[str, list[str]],+ ) -> None:+ state = _query_first(query, "state")+ code = _query_first(query, "code")+ error = _query_first(query, "error")+ if not state or (not code and not error):+ _handler_response(handler, HTTPStatus.BAD_REQUEST, _oauth_html(False))+ return+ completed = OAUTH_FLOWS.complete(state, code=code, error=error)+ _handler_response(+ handler,+ HTTPStatus.OK if completed else HTTPStatus.BAD_REQUEST,+ _oauth_html(completed),+ )++ def _handle_webhook(self, handler: BaseHTTPRequestHandler) -> None:+ raw_length = handler.headers.get("Content-Length")+ try:+ length = int(raw_length or "")+ except ValueError as exc:+ raise LinearWebhookError("invalid content length") from exc+ if length <= 0 or length > MAX_WEBHOOK_BYTES:+ raise LinearWebhookError("invalid content length", HTTPStatus.REQUEST_ENTITY_TOO_LARGE)+ raw = handler.rfile.read(length)+ signature = handler.headers.get("Linear-Signature", "").strip()+ expected = hmac.new(+ self.config.webhook_signing_secret.encode(),+ raw,+ hashlib.sha256,+ ).hexdigest()+ if not signature or not hmac.compare_digest(signature.lower(), expected):+ raise LinearWebhookError("invalid signature", HTTPStatus.UNAUTHORIZED)+ delivery_id = handler.headers.get("Linear-Delivery", "").strip()+ if not delivery_id or len(delivery_id) > 200:+ raise LinearWebhookError("missing delivery id")+ try:+ value: object = json.loads(raw.decode("utf-8"))+ except (UnicodeDecodeError, json.JSONDecodeError) as exc:+ raise LinearWebhookError("invalid JSON") from exc+ if not isinstance(value, dict):+ raise LinearWebhookError("webhook body must be an object")+ payload = cast(dict[str, Any], value)+ timestamp = _webhook_timestamp(payload.get("webhookTimestamp"))+ if timestamp is None or abs(time.time() - timestamp) > MAX_WEBHOOK_AGE_SECONDS:+ raise LinearWebhookError("stale webhook", HTTPStatus.UNAUTHORIZED)+ event_type = payload.get("type")+ if event_type not in WEBHOOK_TYPES:+ _handler_response(handler, HTTPStatus.OK, b'{"ok":true,"ignored":true}', "application/json")+ return+ oauth_client_id = payload.get("oauthClientId")+ if oauth_client_id != self.config.client_id:+ raise LinearWebhookError("webhook belongs to another OAuth app", HTTPStatus.FORBIDDEN)+ self.state.enqueue_webhook(delivery_id, payload)+ _handler_response(handler, HTTPStatus.OK, b'{"ok":true}', "application/json")+++class LinearServerLease:+ def __init__(self, server: SharedLinearHttpServer) -> None:+ self._server = server+ self._closed = False++ def close(self) -> None:+ if self._closed:+ return+ self._closed = True+ _release_server(self._server)+++_SERVER_GUARD = threading.RLock()+_shared_server: SharedLinearHttpServer | None = None+++def acquire_http_server(config: LinearConfig, state: LinearStateStore) -> LinearServerLease:+ global _shared_server+ with _SERVER_GUARD:+ candidate = SharedLinearHttpServer(config, state)+ if _shared_server is None:+ candidate.start()+ _shared_server = candidate+ elif _shared_server.identity != candidate.identity:+ raise RuntimeError(+ "A Linear callback listener is already running with different settings"+ )+ _shared_server._references += 1 # pyright: ignore[reportPrivateUsage]+ return LinearServerLease(_shared_server)+++def _release_server(server: SharedLinearHttpServer) -> None:+ global _shared_server+ with _SERVER_GUARD:+ if _shared_server is not server:+ return+ server._references -= 1 # pyright: ignore[reportPrivateUsage]+ if server._references <= 0: # pyright: ignore[reportPrivateUsage]+ server.close()+ _shared_server = None+++def _handler_response(+ handler: BaseHTTPRequestHandler,+ status: HTTPStatus,+ body: bytes,+ content_type: str = "text/html; charset=utf-8",+) -> None:+ handler.send_response(status.value)+ handler.send_header("Content-Type", content_type)+ handler.send_header("Content-Length", str(len(body)))+ handler.send_header("Cache-Control", "no-store")+ handler.send_header("X-Content-Type-Options", "nosniff")+ handler.end_headers()+ handler.wfile.write(body)+++def _oauth_html(success: bool) -> bytes:+ title = "Linear connected" if success else "Linear connection failed"+ detail = (+ "Authorization received. You can close this window and return to nanobot."+ if success+ else "The authorization request is invalid or expired. Return to nanobot and try again."+ )+ return (+ "<!doctype html><html><head><meta charset=utf-8><title>"+ + title+ + "</title></head><body><main><h1>"+ + title+ + "</h1><p>"+ + detail+ + "</p></main></body></html>"+ ).encode()+++def _query_first(query: dict[str, list[str]], key: str) -> str | None:+ values = query.get(key)+ return values[0] if values and values[0] else None+++def _webhook_timestamp(value: object) -> float | None:+ if isinstance(value, int | float) and not isinstance(value, bool):+ timestamp = float(value)+ return timestamp / 1000 if timestamp > 10_000_000_000 else timestamp+ if not isinstance(value, str) or not value:+ return None+ try:+ timestamp = float(value)+ except ValueError:+ try:+ return datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()+ except ValueError:+ return None+ return timestamp / 1000 if timestamp > 10_000_000_000 else timestampdiff --git a/nanobot/channels/linear/state.py b/nanobot/channels/linear/state.pynew file mode 100644index 000000000..df1e1e818--- /dev/null+++ b/nanobot/channels/linear/state.py@@ -0,0 +1,275 @@+"""Durable installation and webhook state owned by the Linear channel."""++from __future__ import annotations++import json+import os+import sqlite3+import threading+import time+from dataclasses import dataclass+from pathlib import Path+from typing import Any, cast++from nanobot.config.paths import get_config_path, get_runtime_subdir+++@dataclass(frozen=True, slots=True)+class LinearInstallation:+ organization_id: str+ oauth_client_id: str+ app_user_id: str+ access_token: str+ refresh_token: str+ expires_at: float+ scope: tuple[str, ...] = ()+ organization_name: str = ""+++@dataclass(frozen=True, slots=True)+class QueuedWebhook:+ delivery_id: str+ payload: dict[str, Any]+ attempts: int+++class LinearStateStore:+ """Small SQLite store so webhook acknowledgement is durable and idempotent."""++ def __init__(self, path: Path | None = None) -> None:+ self.path = path or (get_runtime_subdir("linear") / "state.sqlite3")+ self.path.parent.mkdir(parents=True, exist_ok=True)+ self._guard = threading.RLock()+ self._initialize()+ try:+ os.chmod(self.path.parent, 0o700)+ os.chmod(self.path, 0o600)+ except OSError:+ pass++ def _connect(self) -> sqlite3.Connection:+ connection = sqlite3.connect(self.path, timeout=10)+ connection.row_factory = sqlite3.Row+ connection.execute("PRAGMA journal_mode=WAL")+ connection.execute("PRAGMA synchronous=FULL")+ return connection++ def _initialize(self) -> None:+ with self._guard, self._connect() as connection:+ connection.executescript(+ """+ CREATE TABLE IF NOT EXISTS installations (+ organization_id TEXT PRIMARY KEY,+ oauth_client_id TEXT NOT NULL,+ app_user_id TEXT NOT NULL,+ access_token TEXT NOT NULL,+ refresh_token TEXT NOT NULL,+ expires_at REAL NOT NULL,+ scope_json TEXT NOT NULL,+ organization_name TEXT NOT NULL,+ updated_at REAL NOT NULL+ );+ CREATE TABLE IF NOT EXISTS webhook_events (+ delivery_id TEXT PRIMARY KEY,+ payload_json TEXT NOT NULL,+ status TEXT NOT NULL DEFAULT 'pending',+ attempts INTEGER NOT NULL DEFAULT 0,+ next_attempt_at REAL NOT NULL DEFAULT 0,+ last_error TEXT,+ created_at REAL NOT NULL+ );+ CREATE TABLE IF NOT EXISTS webhook_receipts (+ delivery_id TEXT PRIMARY KEY,+ received_at REAL NOT NULL+ );+ """+ )+ columns = {+ str(row["name"])+ for row in connection.execute("PRAGMA table_info(installations)").fetchall()+ }+ if "oauth_client_id" not in columns:+ connection.execute(+ "ALTER TABLE installations ADD COLUMN oauth_client_id TEXT NOT NULL DEFAULT ''"+ )+ connection.execute(+ "DELETE FROM webhook_receipts WHERE received_at < ?",+ (time.time() - 30 * 24 * 60 * 60,),+ )++ def has_installations(self, oauth_client_id: str | None = None) -> bool:+ with self._guard, self._connect() as connection:+ if oauth_client_id is None:+ row = connection.execute("SELECT 1 FROM installations LIMIT 1").fetchone()+ else:+ row = connection.execute(+ "SELECT 1 FROM installations WHERE oauth_client_id = ? LIMIT 1",+ (oauth_client_id,),+ ).fetchone()+ return row is not None++ def save_installation(self, installation: LinearInstallation) -> None:+ with self._guard, self._connect() as connection:+ connection.execute(+ """+ INSERT INTO installations (+ organization_id, oauth_client_id, app_user_id, access_token, refresh_token,+ expires_at, scope_json, organization_name, updated_at+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)+ ON CONFLICT(organization_id) DO UPDATE SET+ oauth_client_id=excluded.oauth_client_id,+ app_user_id=excluded.app_user_id,+ access_token=excluded.access_token,+ refresh_token=excluded.refresh_token,+ expires_at=excluded.expires_at,+ scope_json=excluded.scope_json,+ organization_name=excluded.organization_name,+ updated_at=excluded.updated_at+ """,+ (+ installation.organization_id,+ installation.oauth_client_id,+ installation.app_user_id,+ installation.access_token,+ installation.refresh_token,+ installation.expires_at,+ json.dumps(installation.scope),+ installation.organization_name,+ time.time(),+ ),+ )++ def installation(self, organization_id: str) -> LinearInstallation | None:+ with self._guard, self._connect() as connection:+ row = connection.execute(+ "SELECT * FROM installations WHERE organization_id = ?",+ (organization_id,),+ ).fetchone()+ return _installation_from_row(row) if row is not None else None++ def delete_installation(self, organization_id: str) -> None:+ with self._guard, self._connect() as connection:+ connection.execute(+ "DELETE FROM installations WHERE organization_id = ?",+ (organization_id,),+ )++ def enqueue_webhook(self, delivery_id: str, payload: dict[str, Any]) -> bool:+ serialized = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)+ with self._guard, self._connect() as connection:+ connection.execute("BEGIN IMMEDIATE")+ receipt = connection.execute(+ "INSERT OR IGNORE INTO webhook_receipts (delivery_id, received_at) VALUES (?, ?)",+ (delivery_id, time.time()),+ )+ if receipt.rowcount != 1:+ return False+ connection.execute(+ """+ INSERT INTO webhook_events (+ delivery_id, payload_json, status, next_attempt_at, created_at+ ) VALUES (?, ?, 'pending', 0, ?)+ """,+ (delivery_id, serialized, time.time()),+ )+ return True++ def claim_webhooks(self, limit: int = 20) -> list[QueuedWebhook]:+ now = time.time()+ claimed: list[QueuedWebhook] = []+ with self._guard, self._connect() as connection:+ connection.execute("BEGIN IMMEDIATE")+ rows = connection.execute(+ """+ SELECT delivery_id, payload_json, attempts+ FROM webhook_events+ WHERE status = 'pending' AND next_attempt_at <= ?+ ORDER BY created_at+ LIMIT ?+ """,+ (now, limit),+ ).fetchall()+ for row in rows:+ connection.execute(+ "UPDATE webhook_events SET status = 'processing' WHERE delivery_id = ?",+ (row["delivery_id"],),+ )+ value: object = json.loads(str(row["payload_json"]))+ if isinstance(value, dict):+ claimed.append(+ QueuedWebhook(+ delivery_id=str(row["delivery_id"]),+ payload=cast(dict[str, Any], value),+ attempts=int(row["attempts"]),+ )+ )+ return claimed++ def complete_webhook(self, delivery_id: str) -> None:+ with self._guard, self._connect() as connection:+ connection.execute(+ "DELETE FROM webhook_events WHERE delivery_id = ?",+ (delivery_id,),+ )++ def retry_webhook(+ self,+ delivery_id: str,+ error: str,+ attempts: int,+ retry_after: float | None = None,+ ) -> None:+ retry_count = attempts + 1+ if retry_count >= 10:+ status = "failed"+ next_attempt_at = 0.0+ else:+ status = "pending"+ backoff = min(300.0, 2.0**retry_count)+ delay = max(backoff, min(86400.0, retry_after or 0.0))+ next_attempt_at = time.time() + delay+ with self._guard, self._connect() as connection:+ connection.execute(+ """+ UPDATE webhook_events+ SET status = ?, attempts = ?, next_attempt_at = ?, last_error = ?+ WHERE delivery_id = ?+ """,+ (status, retry_count, next_attempt_at, error[:2000], delivery_id),+ )++ def recover_processing_webhooks(self) -> None:+ with self._guard, self._connect() as connection:+ connection.execute(+ "UPDATE webhook_events SET status = 'pending' WHERE status = 'processing'"+ )+++def _installation_from_row(row: sqlite3.Row) -> LinearInstallation:+ raw_scope: object = json.loads(str(row["scope_json"]))+ scope = (+ tuple(str(item) for item in cast(list[object], raw_scope))+ if isinstance(raw_scope, list)+ else ()+ )+ return LinearInstallation(+ organization_id=str(row["organization_id"]),+ oauth_client_id=str(row["oauth_client_id"]),+ app_user_id=str(row["app_user_id"]),+ access_token=str(row["access_token"]),+ refresh_token=str(row["refresh_token"]),+ expires_at=float(row["expires_at"]),+ scope=scope,+ organization_name=str(row["organization_name"]),+ )+++def local_state_present(_section: Any) -> bool:+ """Report OAuth installation state without importing the channel runtime."""+ path = get_config_path().parent / "linear" / "state.sqlite3"+ if not path.is_file():+ return False+ try:+ return LinearStateStore(path).has_installations()+ except (OSError, sqlite3.Error):+ return Falsediff --git a/nanobot/channels/linear/tests/__init__.py b/nanobot/channels/linear/tests/__init__.pynew file mode 100644index 000000000..8088cbda9--- /dev/null+++ b/nanobot/channels/linear/tests/__init__.py@@ -0,0 +1 @@+"""Tests for the native Linear channel."""diff --git a/nanobot/channels/linear/tests/test_linear.py b/nanobot/channels/linear/tests/test_linear.pynew file mode 100644index 000000000..5cc873603--- /dev/null+++ b/nanobot/channels/linear/tests/test_linear.py@@ -0,0 +1,534 @@+from __future__ import annotations++import hashlib+import hmac+import http.client+import json+import socket+import time+from dataclasses import replace+from pathlib import Path+from typing import Any+from urllib.parse import parse_qs, urlparse++import httpx+import pytest++from nanobot.bus.events import OutboundMessage+from nanobot.bus.outbound_events import ProgressEvent+from nanobot.bus.queue import MessageBus+from nanobot.channels.linear.client import LinearApiError, LinearClient+from nanobot.channels.linear.config import LinearConfig, validate_public_base_url+from nanobot.channels.linear.oauth import OAUTH_FLOWS, authorization_url+from nanobot.channels.linear.runtime import LinearChannel+from nanobot.channels.linear.server import acquire_http_server+from nanobot.channels.linear.state import LinearInstallation, LinearStateStore+++def _config(port: int = 3979) -> LinearConfig:+ return LinearConfig(+ client_id="client-id",+ client_secret="client-secret",+ webhook_signing_secret="webhook-secret",+ public_base_url="https://nanobot.example.com",+ host="127.0.0.1",+ port=port,+ allow_from=["*"],+ )+++def _installation() -> LinearInstallation:+ return LinearInstallation(+ organization_id="org-1",+ oauth_client_id="client-id",+ organization_name="Example",+ app_user_id="app-user-1",+ access_token="access",+ refresh_token="refresh",+ expires_at=time.time() + 3600,+ scope=("read", "write", "app:mentionable"),+ )+++def _free_port() -> int:+ with socket.socket() as sock:+ sock.bind(("127.0.0.1", 0))+ return int(sock.getsockname()[1])+++def _post_webhook(+ port: int,+ payload: dict[str, Any],+ *,+ signature: str | None = None,+ delivery: str = "delivery-1",+) -> tuple[int, bytes]:+ raw = json.dumps(payload, separators=(",", ":")).encode()+ actual_signature = signature or hmac.new(b"webhook-secret", raw, hashlib.sha256).hexdigest()+ connection = http.client.HTTPConnection("127.0.0.1", port, timeout=3)+ connection.request(+ "POST",+ "/linear/webhook",+ raw,+ {+ "Content-Type": "application/json",+ "Linear-Signature": actual_signature,+ "Linear-Delivery": delivery,+ },+ )+ response = connection.getresponse()+ body = response.read()+ connection.close()+ return response.status, body+++def _agent_webhook(*, action: str = "created", signal: str = "") -> dict[str, Any]:+ activity: dict[str, Any] | None = None+ if action == "prompted":+ activity = {+ "id": "activity-1",+ "agentSessionId": "session-1",+ "content": {"type": "prompt", "body": "continue the work"},+ "signal": signal or None,+ "userId": "user-1",+ }+ return {+ "type": "AgentSessionEvent",+ "action": action,+ "oauthClientId": "client-id",+ "organizationId": "org-1",+ "webhookTimestamp": int(time.time() * 1000),+ "promptContext": "please investigate this issue",+ "agentActivity": activity,+ "agentSession": {+ "id": "session-1",+ "organizationId": "org-1",+ "creatorId": "user-1",+ "issueId": "issue-1",+ "commentId": "comment-1",+ },+ }+++def test_linear_config_requires_public_https_origin() -> None:+ assert validate_public_base_url("https://nanobot.example.com") == "https://nanobot.example.com"+ assert LinearConfig(public_base_url=" https://nanobot.example.com/ ").public_base_url == (+ "https://nanobot.example.com"+ )+ for value in (+ "http://nanobot.example.com",+ "https://localhost:3979",+ "https://127.0.0.1",+ "https://nanobot.example.com/linear",+ "https://nanobot.example.com:invalid",+ "https://nanobot.example.com:",+ ):+ with pytest.raises(ValueError):+ validate_public_base_url(value)+++def test_linear_config_rejects_overlapping_callback_paths() -> None:+ with pytest.raises(ValueError, match="must be different"):+ LinearConfig(+ webhook_path="/linear/events/",+ oauth_callback_path="/linear/events",+ )+++def test_oauth_authorization_uses_app_actor_pkce_and_mention_scope() -> None:+ flow = OAUTH_FLOWS.create()+ try:+ parsed = urlparse(authorization_url(_config(), flow))+ query = parsed.query+ assert parsed.scheme == "https"+ assert "actor=app" in query+ assert "code_challenge_method=S256" in query+ assert "app%3Amentionable" in query+ assert "app%3Aassignable" not in query+ assert f"state={flow.state}" in query+ finally:+ OAUTH_FLOWS.remove(flow)+++def test_state_store_persists_installations_and_deduplicates_webhooks(tmp_path: Path) -> None:+ store = LinearStateStore(tmp_path / "linear.sqlite3")+ installation = _installation()+ store.save_installation(installation)+ second_installation = replace(+ installation,+ organization_id="org-2",+ organization_name="Second workspace",+ app_user_id="app-user-2",+ access_token="second-access",+ refresh_token="second-refresh",+ )+ store.save_installation(second_installation)++ assert store.installation("org-1") == installation+ assert store.installation("org-2") == second_installation+ assert store.enqueue_webhook("delivery-1", _agent_webhook()) is True+ assert store.enqueue_webhook("delivery-1", _agent_webhook()) is False++ events = store.claim_webhooks()+ assert len(events) == 1+ assert events[0].delivery_id == "delivery-1"+ store.complete_webhook("delivery-1")+ assert store.claim_webhooks() == []+ assert store.enqueue_webhook("delivery-1", _agent_webhook()) is False+++def test_webhook_server_verifies_signature_deduplicates_and_ignores_comments(+ tmp_path: Path,+) -> None:+ port = _free_port()+ config = _config(port)+ store = LinearStateStore(tmp_path / "linear.sqlite3")+ lease = acquire_http_server(config, store)+ try:+ status, _ = _post_webhook(port, _agent_webhook(), signature="invalid")+ assert status == 401++ status, _ = _post_webhook(port, _agent_webhook())+ assert status == 200+ status, _ = _post_webhook(port, _agent_webhook())+ assert status == 200+ assert len(store.claim_webhooks()) == 1++ comment = _agent_webhook()+ comment["type"] = "Comment"+ comment.pop("oauthClientId")+ status, body = _post_webhook(port, comment, delivery="comment-1")+ assert status == 200+ assert b"ignored" in body+ finally:+ lease.close()+++def test_webhook_server_rejects_stale_or_wrong_app_events(tmp_path: Path) -> None:+ port = _free_port()+ store = LinearStateStore(tmp_path / "linear.sqlite3")+ lease = acquire_http_server(_config(port), store)+ try:+ stale = _agent_webhook()+ stale["webhookTimestamp"] = int((time.time() - 120) * 1000)+ assert _post_webhook(port, stale)[0] == 401++ other_app = _agent_webhook()+ other_app["oauthClientId"] = "other-client"+ assert _post_webhook(port, other_app, delivery="other-app")[0] == 403+ finally:+ lease.close()+++def test_oauth_callback_completes_only_registered_state(tmp_path: Path) -> None:+ port = _free_port()+ lease = acquire_http_server(+ _config(port),+ LinearStateStore(tmp_path / "linear.sqlite3"),+ )+ flow = OAUTH_FLOWS.create()+ try:+ connection = http.client.HTTPConnection("127.0.0.1", port, timeout=3)+ connection.request(+ "GET",+ f"/linear/oauth/callback?state={flow.state}&code=authorization-code",+ )+ response = connection.getresponse()+ response.read()+ connection.close()+ assert response.status == 200+ assert flow.code == "authorization-code"+ finally:+ OAUTH_FLOWS.remove(flow)+ lease.close()+++async def test_oauth_exchange_saves_workspace_app_identity_and_required_scopes(+ tmp_path: Path,+) -> None:+ def handler(request: httpx.Request) -> httpx.Response:+ if request.url.path == "/oauth/token":+ return httpx.Response(+ 200,+ json={+ "access_token": "access",+ "refresh_token": "refresh",+ "expires_in": 86400,+ "scope": "read write app:mentionable",+ },+ )+ return httpx.Response(+ 200,+ json={+ "data": {+ "viewer": {+ "id": "app-user-1",+ "organization": {"id": "org-1", "name": "Example"},+ }+ }+ },+ )++ state = LinearStateStore(tmp_path / "linear.sqlite3")+ http = httpx.AsyncClient(transport=httpx.MockTransport(handler))+ client = LinearClient(_config(), state, http)+ try:+ installation = await client.exchange_code("code", "verifier")+ finally:+ await http.aclose()++ assert installation.app_user_id == "app-user-1"+ assert installation.organization_id == "org-1"+ assert state.installation("org-1") == installation+++async def test_oauth_exchange_rejects_missing_mention_scope(tmp_path: Path) -> None:+ def handler(request: httpx.Request) -> httpx.Response:+ if request.url.path == "/oauth/token":+ return httpx.Response(+ 200,+ json={+ "access_token": "access",+ "refresh_token": "refresh",+ "expires_in": 86400,+ "scope": "read write",+ },+ )+ return httpx.Response(+ 200,+ json={+ "data": {+ "viewer": {+ "id": "app-user-1",+ "organization": {"id": "org-1", "name": "Example"},+ }+ }+ },+ )++ state = LinearStateStore(tmp_path / "linear.sqlite3")+ http = httpx.AsyncClient(transport=httpx.MockTransport(handler))+ client = LinearClient(_config(), state, http)+ try:+ with pytest.raises(LinearApiError, match="app:mentionable"):+ await client.exchange_code("code", "verifier")+ finally:+ await http.aclose()++ assert state.has_installations() is False+++async def test_graphql_non_json_server_error_is_retryable(tmp_path: Path) -> None:+ def handler(_request: httpx.Request) -> httpx.Response:+ return httpx.Response(503, text="temporarily unavailable")++ state = LinearStateStore(tmp_path / "linear.sqlite3")+ state.save_installation(_installation())+ http = httpx.AsyncClient(transport=httpx.MockTransport(handler))+ client = LinearClient(_config(), state, http)+ try:+ with pytest.raises(LinearApiError) as error:+ await client.graphql("org-1", "query Test { viewer { id } }", {})+ finally:+ await http.aclose()++ assert error.value.retryable is True+++async def test_graphql_rate_limit_error_is_retryable(tmp_path: Path) -> None:+ reset_at = int((time.time() + 60) * 1000)++ def handler(_request: httpx.Request) -> httpx.Response:+ return httpx.Response(+ 400,+ headers={"X-RateLimit-Requests-Reset": str(reset_at)},+ json={+ "errors": [{+ "message": "Request limit exceeded",+ "extensions": {"code": "RATELIMITED"},+ }]+ },+ )++ state = LinearStateStore(tmp_path / "linear.sqlite3")+ state.save_installation(_installation())+ http = httpx.AsyncClient(transport=httpx.MockTransport(handler))+ client = LinearClient(_config(), state, http)+ try:+ with pytest.raises(LinearApiError, match="Request limit exceeded") as error:+ await client.graphql("org-1", "query Test { viewer { id } }", {})+ finally:+ await http.aclose()++ assert error.value.retryable is True+ assert error.value.retry_after is not None+ assert 50 <= error.value.retry_after <= 60+++async def test_expired_workspace_token_is_refreshed_and_rotated(tmp_path: Path) -> None:+ seen_refresh_form: dict[str, list[str]] = {}++ def handler(request: httpx.Request) -> httpx.Response:+ if request.url.path == "/oauth/token":+ seen_refresh_form.update(parse_qs(request.content.decode()))+ return httpx.Response(+ 200,+ json={+ "access_token": "rotated-access",+ "refresh_token": "rotated-refresh",+ "expires_in": 86400,+ "scope": "read write app:mentionable",+ },+ )+ assert request.headers["Authorization"] == "Bearer rotated-access"+ return httpx.Response(200, json={"data": {"viewer": {"id": "app-user-1"}}})++ state = LinearStateStore(tmp_path / "linear.sqlite3")+ state.save_installation(replace(_installation(), expires_at=time.time() - 1))+ http = httpx.AsyncClient(transport=httpx.MockTransport(handler))+ client = LinearClient(_config(), state, http)+ try:+ data = await client.graphql("org-1", "query Test { viewer { id } }", {})+ finally:+ await http.aclose()++ assert data["viewer"] == {"id": "app-user-1"}+ assert seen_refresh_form["grant_type"] == ["refresh_token"]+ assert seen_refresh_form["refresh_token"] == ["refresh"]+ refreshed = state.installation("org-1")+ assert refreshed is not None+ assert refreshed.access_token == "rotated-access"+ assert refreshed.refresh_token == "rotated-refresh"+++class _FakeLinearClient:+ def __init__(self) -> None:+ self.activities: list[dict[str, Any]] = []++ async def create_activity(+ self,+ organization_id: str,+ agent_session_id: str,+ content: dict[str, Any],+ *,+ activity_id: str,+ ephemeral: bool = False,+ ) -> None:+ self.activities.append(+ {+ "organization_id": organization_id,+ "agent_session_id": agent_session_id,+ "content": content,+ "activity_id": activity_id,+ "ephemeral": ephemeral,+ }+ )+++def _runtime(tmp_path: Path) -> tuple[LinearChannel, _FakeLinearClient]:+ channel = LinearChannel(_config(), MessageBus())+ state = LinearStateStore(tmp_path / "linear.sqlite3")+ state.save_installation(_installation())+ fake = _FakeLinearClient()+ channel._state = state # pyright: ignore[reportPrivateUsage]+ channel._client = fake # type: ignore[assignment] # pyright: ignore[reportPrivateUsage]+ return channel, fake+++async def test_created_agent_session_publishes_only_the_mention_prompt(tmp_path: Path) -> None:+ channel, client = _runtime(tmp_path)+ await channel._process_webhook("delivery-1", _agent_webhook()) # pyright: ignore[reportPrivateUsage]++ inbound = await channel.bus.consume_inbound()+ assert inbound.content == "please investigate this issue"+ assert inbound.sender_id == "user-1"+ assert inbound.chat_id == "session-1"+ assert inbound.session_key == "linear:org-1:session-1"+ assert inbound.metadata["linear"]["issue_id"] == "issue-1"+ assert client.activities[0]["content"] == {"type": "thought", "body": "Starting…"}+++async def test_prompted_stop_signal_becomes_priority_stop_command(tmp_path: Path) -> None:+ channel, _ = _runtime(tmp_path)+ await channel._process_webhook( # pyright: ignore[reportPrivateUsage]+ "delivery-2",+ _agent_webhook(action="prompted", signal="stop"),+ )++ inbound = await channel.bus.consume_inbound()+ assert inbound.content == "/stop"+ assert inbound.metadata["linear"]["signal"] == "stop"+++async def test_app_authored_activity_is_not_echoed_back(tmp_path: Path) -> None:+ channel, _ = _runtime(tmp_path)+ payload = _agent_webhook(action="prompted")+ payload["agentActivity"]["userId"] = "app-user-1"++ await channel._process_webhook("delivery-3", payload) # pyright: ignore[reportPrivateUsage]++ assert channel.bus.inbound.empty()+++async def test_outbound_response_and_tool_progress_use_native_activity_shapes(+ tmp_path: Path,+) -> None:+ channel, client = _runtime(tmp_path)+ metadata = {+ "linear": {+ "organization_id": "org-1",+ "agent_session_id": "session-1",+ }+ }+ response = OutboundMessage(+ channel="linear",+ chat_id="session-1",+ content="Done",+ metadata=metadata,+ )+ await channel.send(response)+ activity_id = client.activities[-1]["activity_id"]+ await channel.send(response)++ tool = OutboundMessage(+ channel="linear",+ chat_id="session-1",+ content="",+ metadata=metadata,+ event=ProgressEvent(+ tool_events=[{+ "phase": "end",+ "call_id": "call-1",+ "name": "linear_get_issue",+ "arguments": {"id": "issue-1"},+ "result": {"title": "Bug"},+ }]+ ),+ )+ await channel.send(tool)++ assert client.activities[0]["content"] == {"type": "response", "body": "Done"}+ assert client.activities[1]["activity_id"] == activity_id+ assert client.activities[2]["content"]["type"] == "action"+ assert client.activities[2]["content"]["action"] == "linear_get_issue"+++def test_revocation_removes_workspace_installation(tmp_path: Path) -> None:+ channel, _ = _runtime(tmp_path)+ channel._process_lifecycle_event( # pyright: ignore[reportPrivateUsage]+ {+ "type": "OAuthApp",+ "action": "revoked",+ "organizationId": "org-1",+ }+ )+ assert channel._state.installation("org-1") is None # pyright: ignore[reportPrivateUsage]diff --git a/nanobot/channels/linear/validation.py b/nanobot/channels/linear/validation.pynew file mode 100644index 000000000..4cf002ce9--- /dev/null+++ b/nanobot/channels/linear/validation.py@@ -0,0 +1,40 @@+"""Setup validation for Linear's public callback requirements."""++from typing import Any++from pydantic import ValidationError++from nanobot.channels.contracts import ChannelValidationContext+from nanobot.channels.linear.config import LinearConfig+from nanobot.channels.validation import check, required_checks, status_from_checks+++def validate(values: dict[str, Any], _context: ChannelValidationContext) -> dict[str, Any]:+ checks, missing = required_checks("linear", values)+ try:+ config = LinearConfig.model_validate(values)+ config.validate_runtime()+ except (ValidationError, ValueError) as exc:+ checks.append(check("callbacks", "Public callbacks", "fail", str(exc)))+ else:+ checks.append(+ check(+ "callbacks",+ "Public callbacks",+ "pass",+ f"Webhook: {config.webhook_url}; OAuth callback: {config.redirect_uri}",+ )+ )+ checks.append(+ check(+ "linear_app",+ "Linear OAuth app",+ "skipped",+ "OAuth credentials and scopes are verified when you connect; "+ "webhook delivery is verified by the first event.",+ )+ )+ return status_from_checks("linear", checks, missing)+++__all__ = ["validate"]diff --git a/nanobot/channels/linear/webui/LinearConnectFlow.tsx b/nanobot/channels/linear/webui/LinearConnectFlow.tsxnew file mode 100644index 000000000..558424cdd--- /dev/null+++ b/nanobot/channels/linear/webui/LinearConnectFlow.tsx@@ -0,0 +1,118 @@+import { ExternalLink } from "lucide-react";+import { useTranslation } from "react-i18next";++import { channelTranslator } from "@/channel-plugins/i18n";+import { ChannelQrConnectFlow } from "@/components/settings/channels/ChannelQrConnectFlow";+import { Button } from "@/components/ui/button";+import type { ChannelPluginConnectFlowProps } from "@/channel-plugins/types";++export function LinearConnectFlow({+ token,+ feature,+ idleLabel,+ connectRequestId,+ onFeaturesUpdate,+}: ChannelPluginConnectFlowProps) {+ const { t } = useTranslation();+ const tx = channelTranslator(t, "linear");+ const publicBaseUrl = feature.config_values?.["channels.linear.publicBaseUrl"]?.replace(/\/$/, "");+ const webhookPath = feature.config_values?.["channels.linear.webhookPath"] || "/linear/webhook";+ const callbackPath = feature.config_values?.["channels.linear.oauthCallbackPath"] || "/linear/oauth/callback";+ const manifestUrl = publicBaseUrl+ ? linearManifestUrl(publicBaseUrl, webhookPath, callbackPath)+ : null;++ return (+ <div className="mt-3 space-y-3">+ {manifestUrl ? (+ <div className="flex justify-end">+ <Button+ type="button"+ size="sm"+ variant="outline"+ className="h-8 rounded-full px-3 text-[12px] font-semibold"+ onClick={() => window.open(manifestUrl, "_blank", "noopener,noreferrer")}+ >+ <ExternalLink className="mr-1.5 h-3.5 w-3.5" aria-hidden />+ {t("settings.channels.createApp", { defaultValue: "Create prefilled Linear app" })}+ </Button>+ </div>+ ) : null}+ <ChannelQrConnectFlow+ token={token}+ channelName="linear"+ idleLabel={idleLabel}+ connectRequestId={connectRequestId}+ forceOnRepeat+ onFeaturesUpdate={onFeaturesUpdate}+ labels={{+ qrAlt: tx("custom.qrAlt", "Linear authorization QR code"),+ scanTitle: tx("custom.authorizeTitle", "Authorize in Linear"),+ scanDescription: tx(+ "custom.authorizeDescription",+ "Open Linear in this browser or scan the QR code. nanobot enables the channel after authorization.",+ ),+ waiting: tx("custom.waiting", "Waiting for Linear authorization..."),+ connected: tx("custom.connected", "Linear is connected."),+ stopped: tx("custom.stopped", "Authorization stopped."),+ connecting: tx("custom.connecting", "Connecting..."),+ scanAgain: tx("custom.reconnect", "Connect another workspace"),+ connect: tx("custom.connect", "Connect Linear"),+ }}+ renderPending={({ connect }) => (+ <div className="mt-3 space-y-3">+ <div className="flex items-center gap-2 text-[12px] text-muted-foreground">+ <span className="h-2 w-2 animate-pulse rounded-full bg-[#5E6AD2]" aria-hidden />+ {tx("custom.waiting", "Waiting for Linear authorization...")}+ </div>+ {connect.qr_url ? (+ <Button+ type="button"+ size="sm"+ className="h-8 rounded-full px-3 text-[12px] font-semibold"+ onClick={() => window.open(connect.qr_url, "_blank", "noopener,noreferrer")}+ >+ <ExternalLink className="mr-1.5 h-3.5 w-3.5" aria-hidden />+ {tx("custom.openLinear", "Continue in Linear")}+ </Button>+ ) : null}+ </div>+ )}+ />+ </div>+ );+}++export function linearManifestUrl(+ publicBaseUrl: string,+ webhookPath: string,+ callbackPath: string,+): string {+ const manifest = {+ $schema: "https://linear.app/.well-known/oauth-app-manifest.schema.json",+ schemaVersion: "1.0.0",+ distribution: "private",+ display: {+ description: "Use nanobot as a native issue agent.",+ },+ developer: { name: "nanobot" },+ oauth: {+ client_name: "nanobot Agent",+ client_uri: publicBaseUrl,+ redirect_uris: [`${publicBaseUrl}${callbackPath}`],+ grant_types: ["authorization_code"],+ },+ webhook: {+ enabled: true,+ url: `${publicBaseUrl}${webhookPath}`,+ resourceTypes: [+ "AgentSessionEvent",+ "PermissionChange",+ "OAuthAuthorization",+ ],+ },+ };+ return `https://linear.app/settings/api/applications/new?${new URLSearchParams({+ manifest: JSON.stringify(manifest),+ })}`;+}diff --git a/nanobot/channels/linear/webui/index.tsx b/nanobot/channels/linear/webui/index.tsxnew file mode 100644index 000000000..a1d298151--- /dev/null+++ b/nanobot/channels/linear/webui/index.tsx@@ -0,0 +1,37 @@+import { lazy } from "react";++import type { ChannelUiContribution } from "@/channel-plugins/types";+import { chatAppGuideUrl } from "@/components/settings/channels/catalog";++const LinearConnectFlow = lazy(() =>+ import("./LinearConnectFlow").then(({ LinearConnectFlow: component }) => ({+ default: component,+ })),+);++export default {+ ConnectFlow: LinearConnectFlow,+ presentation: {+ displayName: "Linear",+ initials: "LI",+ color: "#5E6AD2",+ logoUrl: "https://linear.app/favicon.ico",+ setup: {+ mode: "connect",+ docsUrl: chatAppGuideUrl("linear"),+ fields: [+ { key: "channels.linear.clientId" },+ { key: "channels.linear.clientSecret" },+ { key: "channels.linear.webhookSigningSecret" },+ { key: "channels.linear.publicBaseUrl" },+ ],+ manualFields: [+ { key: "channels.linear.host" },+ { key: "channels.linear.port" },+ { key: "channels.linear.webhookPath" },+ { key: "channels.linear.oauthCallbackPath" },+ { key: "channels.linear.allowFrom" },+ ],+ },+ },+} satisfies ChannelUiContribution;diff --git a/nanobot/channels/linear/webui/locales/en.json b/nanobot/channels/linear/webui/locales/en.jsonnew file mode 100644index 000000000..846bbabc0--- /dev/null+++ b/nanobot/channels/linear/webui/locales/en.json@@ -0,0 +1,71 @@+{+ "description": "Work with nanobot from Linear issues through native Agent Sessions.",+ "requirements": "A private Linear OAuth app and a stable public HTTPS callback URL",+ "setup": {+ "docsLabel": "Open Linear setup guide",+ "officialLabel": "Create Linear OAuth app",+ "tryIt": "Mention the app in an issue comment. Follow-ups inside its Agent Session do not need another mention.",+ "summary": "Create a private Linear OAuth app, save its credentials and public URL, then authorize each workspace. New sessions require an explicit @mention; ordinary comments are ignored.",+ "steps": [+ "Expose this nanobot instance through a stable HTTPS URL (a tunnel is fine).",+ "Create a private OAuth app in Linear with read, write, and app:mentionable scopes. Do not add app:assignable.",+ "Subscribe the app webhook to AgentSessionEvent, PermissionChange, and OAuthAuthorization using the generated webhook URL.",+ "Save settings, connect the workspace with OAuth, then @mention the app on an issue."+ ],+ "fields": {+ "clientId": {+ "label": "OAuth client ID",+ "placeholder": "Linear OAuth client ID",+ "help": "Copy it from the private OAuth app in Linear."+ },+ "clientSecret": {+ "label": "OAuth client secret",+ "placeholder": "••••••",+ "help": "Stored only by this nanobot instance."+ },+ "webhookSigningSecret": {+ "label": "Webhook signing secret",+ "placeholder": "••••••",+ "help": "Used to verify Linear-Signature before any webhook body is parsed."+ },+ "publicBaseUrl": {+ "label": "Public HTTPS URL",+ "placeholder": "https://nanobot.example.com",+ "help": "A stable HTTPS origin routed to the listener below; do not include a path."+ },+ "host": {+ "label": "Listen host",+ "placeholder": "0.0.0.0"+ },+ "port": {+ "label": "Listen port",+ "placeholder": "3979"+ },+ "webhookPath": {+ "label": "Webhook path",+ "placeholder": "/linear/webhook"+ },+ "oauthCallbackPath": {+ "label": "OAuth callback path",+ "placeholder": "/linear/oauth/callback"+ },+ "allowFrom": {+ "label": "Allowed Linear users",+ "placeholder": "Linear user IDs, comma separated",+ "help": "Leave empty to use nanobot pairing, or use * to allow every user in connected workspaces."+ }+ }+ },+ "custom": {+ "qrAlt": "Linear authorization QR code",+ "authorizeTitle": "Authorize in Linear",+ "authorizeDescription": "Open Linear in this browser or scan the QR code. nanobot enables the channel after authorization.",+ "waiting": "Waiting for Linear authorization...",+ "connected": "Linear is connected.",+ "stopped": "Authorization stopped.",+ "connecting": "Connecting...",+ "reconnect": "Connect another workspace",+ "connect": "Connect Linear",+ "openLinear": "Continue in Linear"+ }+}diff --git a/nanobot/channels/linear/webui/locales/es.json b/nanobot/channels/linear/webui/locales/es.jsonnew file mode 100644index 000000000..eb5deb090--- /dev/null+++ b/nanobot/channels/linear/webui/locales/es.json@@ -0,0 +1,71 @@+{+ "description": "Trabaja con nanobot desde incidencias de Linear mediante sesiones de agente nativas.",+ "requirements": "Una aplicación OAuth privada de Linear y una URL HTTPS pública y estable para las devoluciones de llamada",+ "setup": {+ "docsLabel": "Abrir la guía de configuración de Linear",+ "officialLabel": "Crear una aplicación OAuth de Linear",+ "tryIt": "Menciona la aplicación en un comentario de una incidencia. Las respuestas dentro de su sesión de agente no necesitan otra mención.",+ "summary": "Crea una aplicación OAuth privada de Linear, guarda sus credenciales y la URL pública y, después, autoriza el espacio de trabajo. Cada sesión nueva requiere una @mención explícita; los comentarios normales se ignoran.",+ "steps": [+ "Expón esta instancia de nanobot mediante una URL HTTPS estable (puedes usar un túnel).",+ "Crea una aplicación OAuth privada en Linear con los permisos read, write y app:mentionable. No añadas app:assignable.",+ "Suscribe el webhook de la aplicación a AgentSessionEvent, PermissionChange y OAuthAuthorization con la URL generada.",+ "Guarda la configuración, conecta el espacio de trabajo mediante OAuth y @menciona la aplicación en una incidencia."+ ],+ "fields": {+ "clientId": {+ "label": "ID de cliente OAuth",+ "placeholder": "ID de cliente OAuth de Linear",+ "help": "Cópialo de la aplicación OAuth privada en Linear."+ },+ "clientSecret": {+ "label": "Secreto de cliente OAuth",+ "placeholder": "••••••",+ "help": "Solo se guarda en esta instancia de nanobot."+ },+ "webhookSigningSecret": {+ "label": "Secreto de firma del webhook",+ "placeholder": "••••••",+ "help": "Se usa para verificar Linear-Signature antes de analizar el cuerpo del webhook."+ },+ "publicBaseUrl": {+ "label": "URL HTTPS pública",+ "placeholder": "https://nanobot.example.com",+ "help": "Un origen HTTPS estable dirigido al listener indicado abajo; no incluyas una ruta."+ },+ "host": {+ "label": "Host de escucha",+ "placeholder": "0.0.0.0"+ },+ "port": {+ "label": "Puerto de escucha",+ "placeholder": "3979"+ },+ "webhookPath": {+ "label": "Ruta del webhook",+ "placeholder": "/linear/webhook"+ },+ "oauthCallbackPath": {+ "label": "Ruta de devolución OAuth",+ "placeholder": "/linear/oauth/callback"+ },+ "allowFrom": {+ "label": "Usuarios de Linear permitidos",+ "placeholder": "ID de usuarios de Linear separados por comas",+ "help": "Déjalo vacío para usar el emparejamiento de nanobot, o usa * para permitir a todos los usuarios de los espacios conectados."+ }+ }+ },+ "custom": {+ "qrAlt": "Código QR de autorización de Linear",+ "authorizeTitle": "Autorizar en Linear",+ "authorizeDescription": "Abre Linear en este navegador o escanea el código QR. nanobot habilitará el canal después de la autorización.",+ "waiting": "Esperando la autorización de Linear...",+ "connected": "Linear está conectado.",+ "stopped": "La autorización se detuvo.",+ "connecting": "Conectando...",+ "reconnect": "Conectar otro espacio de trabajo",+ "connect": "Conectar Linear",+ "openLinear": "Continuar en Linear"+ }+}diff --git a/nanobot/channels/linear/webui/locales/fr.json b/nanobot/channels/linear/webui/locales/fr.jsonnew file mode 100644index 000000000..53742c966--- /dev/null+++ b/nanobot/channels/linear/webui/locales/fr.json@@ -0,0 +1,71 @@+{+ "description": "Utilisez nanobot depuis les tickets Linear grâce aux sessions d’agent natives.",+ "requirements": "Une application OAuth Linear privée et une URL de rappel HTTPS publique et stable",+ "setup": {+ "docsLabel": "Ouvrir le guide de configuration Linear",+ "officialLabel": "Créer une application OAuth Linear",+ "tryIt": "Mentionnez l’application dans un commentaire de ticket. Les messages suivants dans sa session d’agent ne nécessitent pas de nouvelle mention.",+ "summary": "Créez une application OAuth Linear privée, enregistrez ses identifiants et son URL publique, puis autorisez l’espace de travail. Chaque nouvelle session exige une @mention explicite ; les commentaires ordinaires sont ignorés.",+ "steps": [+ "Exposez cette instance nanobot avec une URL HTTPS stable (un tunnel convient).",+ "Créez une application OAuth privée dans Linear avec les autorisations read, write et app:mentionable. N’ajoutez pas app:assignable.",+ "Abonnez le webhook de l’application à AgentSessionEvent, PermissionChange et OAuthAuthorization avec l’URL générée.",+ "Enregistrez les paramètres, connectez l’espace de travail avec OAuth, puis @mentionnez l’application dans un ticket."+ ],+ "fields": {+ "clientId": {+ "label": "ID client OAuth",+ "placeholder": "ID client OAuth Linear",+ "help": "Copiez-le depuis l’application OAuth privée dans Linear."+ },+ "clientSecret": {+ "label": "Secret client OAuth",+ "placeholder": "••••••",+ "help": "Enregistré uniquement sur cette instance nanobot."+ },+ "webhookSigningSecret": {+ "label": "Secret de signature du webhook",+ "placeholder": "••••••",+ "help": "Utilisé pour vérifier Linear-Signature avant toute analyse du contenu du webhook."+ },+ "publicBaseUrl": {+ "label": "URL HTTPS publique",+ "placeholder": "https://nanobot.example.com",+ "help": "Une origine HTTPS stable acheminée vers l’écouteur ci-dessous ; n’incluez pas de chemin."+ },+ "host": {+ "label": "Hôte d’écoute",+ "placeholder": "0.0.0.0"+ },+ "port": {+ "label": "Port d’écoute",+ "placeholder": "3979"+ },+ "webhookPath": {+ "label": "Chemin du webhook",+ "placeholder": "/linear/webhook"+ },+ "oauthCallbackPath": {+ "label": "Chemin de rappel OAuth",+ "placeholder": "/linear/oauth/callback"+ },+ "allowFrom": {+ "label": "Utilisateurs Linear autorisés",+ "placeholder": "ID utilisateur Linear séparés par des virgules",+ "help": "Laissez vide pour utiliser l’association nanobot, ou saisissez * pour autoriser tous les utilisateurs des espaces connectés."+ }+ }+ },+ "custom": {+ "qrAlt": "Code QR d’autorisation Linear",+ "authorizeTitle": "Autoriser dans Linear",+ "authorizeDescription": "Ouvrez Linear dans ce navigateur ou scannez le code QR. nanobot activera le canal après l’autorisation.",+ "waiting": "En attente de l’autorisation Linear...",+ "connected": "Linear est connecté.",+ "stopped": "L’autorisation a été interrompue.",+ "connecting": "Connexion...",+ "reconnect": "Connecter un autre espace de travail",+ "connect": "Connecter Linear",+ "openLinear": "Continuer dans Linear"+ }+}diff --git a/nanobot/channels/linear/webui/locales/id.json b/nanobot/channels/linear/webui/locales/id.jsonnew file mode 100644index 000000000..d00e5907c--- /dev/null+++ b/nanobot/channels/linear/webui/locales/id.json@@ -0,0 +1,71 @@+{+ "description": "Gunakan nanobot dari issue Linear melalui Agent Session native.",+ "requirements": "Aplikasi OAuth Linear privat dan URL callback HTTPS publik yang stabil",+ "setup": {+ "docsLabel": "Buka panduan penyiapan Linear",+ "officialLabel": "Buat aplikasi OAuth Linear",+ "tryIt": "Mention aplikasi dalam komentar issue. Pesan lanjutan di Agent Session tidak memerlukan mention lagi.",+ "summary": "Buat aplikasi OAuth Linear privat, simpan kredensial dan URL publiknya, lalu otorisasi workspace. Setiap sesi baru memerlukan @mention eksplisit; komentar biasa akan diabaikan.",+ "steps": [+ "Ekspos instans nanobot ini melalui URL HTTPS yang stabil (tunnel dapat digunakan).",+ "Buat aplikasi OAuth privat di Linear dengan scope read, write, dan app:mentionable. Jangan tambahkan app:assignable.",+ "Daftarkan webhook aplikasi untuk AgentSessionEvent, PermissionChange, dan OAuthAuthorization menggunakan URL yang dibuat.",+ "Simpan pengaturan, hubungkan workspace melalui OAuth, lalu @mention aplikasi pada issue."+ ],+ "fields": {+ "clientId": {+ "label": "ID klien OAuth",+ "placeholder": "ID klien OAuth Linear",+ "help": "Salin dari aplikasi OAuth privat di Linear."+ },+ "clientSecret": {+ "label": "Secret klien OAuth",+ "placeholder": "••••••",+ "help": "Hanya disimpan oleh instans nanobot ini."+ },+ "webhookSigningSecret": {+ "label": "Secret penandatanganan webhook",+ "placeholder": "••••••",+ "help": "Digunakan untuk memverifikasi Linear-Signature sebelum isi webhook diurai."+ },+ "publicBaseUrl": {+ "label": "URL HTTPS publik",+ "placeholder": "https://nanobot.example.com",+ "help": "Origin HTTPS stabil yang diarahkan ke listener di bawah; jangan sertakan path."+ },+ "host": {+ "label": "Host listener",+ "placeholder": "0.0.0.0"+ },+ "port": {+ "label": "Port listener",+ "placeholder": "3979"+ },+ "webhookPath": {+ "label": "Path webhook",+ "placeholder": "/linear/webhook"+ },+ "oauthCallbackPath": {+ "label": "Path callback OAuth",+ "placeholder": "/linear/oauth/callback"+ },+ "allowFrom": {+ "label": "Pengguna Linear yang diizinkan",+ "placeholder": "ID pengguna Linear, dipisahkan koma",+ "help": "Biarkan kosong untuk memakai pairing nanobot, atau gunakan * untuk mengizinkan semua pengguna di workspace yang terhubung."+ }+ }+ },+ "custom": {+ "qrAlt": "Kode QR otorisasi Linear",+ "authorizeTitle": "Otorisasi di Linear",+ "authorizeDescription": "Buka Linear di browser ini atau pindai kode QR. nanobot akan mengaktifkan channel setelah otorisasi.",+ "waiting": "Menunggu otorisasi Linear...",+ "connected": "Linear telah terhubung.",+ "stopped": "Otorisasi dihentikan.",+ "connecting": "Menghubungkan...",+ "reconnect": "Hubungkan workspace lain",+ "connect": "Hubungkan Linear",+ "openLinear": "Lanjutkan di Linear"+ }+}diff --git a/nanobot/channels/linear/webui/locales/ja.json b/nanobot/channels/linear/webui/locales/ja.jsonnew file mode 100644index 000000000..847799155--- /dev/null+++ b/nanobot/channels/linear/webui/locales/ja.json@@ -0,0 +1,71 @@+{+ "description": "Linear の issue からネイティブ Agent Session を通じて nanobot を利用します。",+ "requirements": "非公開の Linear OAuth アプリと、安定した公開 HTTPS コールバック URL",+ "setup": {+ "docsLabel": "Linear セットアップガイドを開く",+ "officialLabel": "Linear OAuth アプリを作成",+ "tryIt": "issue のコメントでアプリをメンションしてください。Agent Session 内の続きのメッセージでは、再度メンションする必要はありません。",+ "summary": "非公開の Linear OAuth アプリを作成し、認証情報と公開 URL を保存してからワークスペースを認証します。新しいセッションの開始には明示的な @メンションが必要で、通常のコメントは無視されます。",+ "steps": [+ "この nanobot インスタンスを安定した HTTPS URL で公開します(トンネルも利用できます)。",+ "Linear で read、write、app:mentionable スコープを持つ非公開 OAuth アプリを作成します。app:assignable は追加しないでください。",+ "生成された URL を使い、アプリの webhook を AgentSessionEvent、PermissionChange、OAuthAuthorization に登録します。",+ "設定を保存し、OAuth でワークスペースを接続してから、issue でアプリを @メンションします。"+ ],+ "fields": {+ "clientId": {+ "label": "OAuth クライアント ID",+ "placeholder": "Linear OAuth クライアント ID",+ "help": "Linear の非公開 OAuth アプリからコピーします。"+ },+ "clientSecret": {+ "label": "OAuth クライアントシークレット",+ "placeholder": "••••••",+ "help": "この nanobot インスタンス内にのみ保存されます。"+ },+ "webhookSigningSecret": {+ "label": "Webhook 署名シークレット",+ "placeholder": "••••••",+ "help": "Webhook の本文を解析する前に Linear-Signature を検証するために使います。"+ },+ "publicBaseUrl": {+ "label": "公開 HTTPS URL",+ "placeholder": "https://nanobot.example.com",+ "help": "下のリスナーへ転送される安定した HTTPS オリジンを指定します。パスは含めないでください。"+ },+ "host": {+ "label": "リッスンホスト",+ "placeholder": "0.0.0.0"+ },+ "port": {+ "label": "リッスンポート",+ "placeholder": "3979"+ },+ "webhookPath": {+ "label": "Webhook パス",+ "placeholder": "/linear/webhook"+ },+ "oauthCallbackPath": {+ "label": "OAuth コールバックパス",+ "placeholder": "/linear/oauth/callback"+ },+ "allowFrom": {+ "label": "許可する Linear ユーザー",+ "placeholder": "Linear ユーザー ID(カンマ区切り)",+ "help": "nanobot のペアリングを使う場合は空欄にします。接続済みワークスペースの全ユーザーを許可する場合のみ * を指定してください。"+ }+ }+ },+ "custom": {+ "qrAlt": "Linear 認証 QR コード",+ "authorizeTitle": "Linear で認証",+ "authorizeDescription": "このブラウザで Linear を開くか、QR コードを読み取ってください。認証後、nanobot がチャンネルを有効にします。",+ "waiting": "Linear の認証を待っています...",+ "connected": "Linear に接続しました。",+ "stopped": "認証を中止しました。",+ "connecting": "接続しています...",+ "reconnect": "別のワークスペースを接続",+ "connect": "Linear に接続",+ "openLinear": "Linear で続行"+ }+}diff --git a/nanobot/channels/linear/webui/locales/ko.json b/nanobot/channels/linear/webui/locales/ko.jsonnew file mode 100644index 000000000..34bf8cbdb--- /dev/null+++ b/nanobot/channels/linear/webui/locales/ko.json@@ -0,0 +1,71 @@+{+ "description": "Linear 이슈에서 네이티브 Agent Session을 통해 nanobot을 사용합니다.",+ "requirements": "비공개 Linear OAuth 앱과 안정적인 공개 HTTPS 콜백 URL",+ "setup": {+ "docsLabel": "Linear 설정 가이드 열기",+ "officialLabel": "Linear OAuth 앱 만들기",+ "tryIt": "이슈 댓글에서 앱을 멘션하세요. Agent Session 안의 후속 메시지에는 다시 멘션할 필요가 없습니다.",+ "summary": "비공개 Linear OAuth 앱을 만들고 인증 정보와 공개 URL을 저장한 다음 워크스페이스를 승인하세요. 새 세션은 명시적인 @멘션으로만 시작되며 일반 댓글은 무시됩니다.",+ "steps": [+ "이 nanobot 인스턴스를 안정적인 HTTPS URL로 공개하세요(터널을 사용할 수 있습니다).",+ "Linear에서 read, write, app:mentionable 범위가 있는 비공개 OAuth 앱을 만드세요. app:assignable은 추가하지 마세요.",+ "생성된 URL로 앱 webhook을 AgentSessionEvent, PermissionChange, OAuthAuthorization에 구독하세요.",+ "설정을 저장하고 OAuth로 워크스페이스를 연결한 다음 이슈에서 앱을 @멘션하세요."+ ],+ "fields": {+ "clientId": {+ "label": "OAuth 클라이언트 ID",+ "placeholder": "Linear OAuth 클라이언트 ID",+ "help": "Linear의 비공개 OAuth 앱에서 복사하세요."+ },+ "clientSecret": {+ "label": "OAuth 클라이언트 시크릿",+ "placeholder": "••••••",+ "help": "이 nanobot 인스턴스에만 저장됩니다."+ },+ "webhookSigningSecret": {+ "label": "Webhook 서명 시크릿",+ "placeholder": "••••••",+ "help": "Webhook 본문을 파싱하기 전에 Linear-Signature를 검증하는 데 사용됩니다."+ },+ "publicBaseUrl": {+ "label": "공개 HTTPS URL",+ "placeholder": "https://nanobot.example.com",+ "help": "아래 리스너로 연결되는 안정적인 HTTPS 오리진입니다. 경로는 포함하지 마세요."+ },+ "host": {+ "label": "수신 호스트",+ "placeholder": "0.0.0.0"+ },+ "port": {+ "label": "수신 포트",+ "placeholder": "3979"+ },+ "webhookPath": {+ "label": "Webhook 경로",+ "placeholder": "/linear/webhook"+ },+ "oauthCallbackPath": {+ "label": "OAuth 콜백 경로",+ "placeholder": "/linear/oauth/callback"+ },+ "allowFrom": {+ "label": "허용된 Linear 사용자",+ "placeholder": "쉼표로 구분한 Linear 사용자 ID",+ "help": "nanobot 페어링을 사용하려면 비워 두세요. 연결된 워크스페이스의 모든 사용자를 허용하려면 *를 사용하세요."+ }+ }+ },+ "custom": {+ "qrAlt": "Linear 승인 QR 코드",+ "authorizeTitle": "Linear에서 승인",+ "authorizeDescription": "이 브라우저에서 Linear를 열거나 QR 코드를 스캔하세요. 승인 후 nanobot이 채널을 활성화합니다.",+ "waiting": "Linear 승인을 기다리는 중...",+ "connected": "Linear가 연결되었습니다.",+ "stopped": "승인이 중지되었습니다.",+ "connecting": "연결 중...",+ "reconnect": "다른 워크스페이스 연결",+ "connect": "Linear 연결",+ "openLinear": "Linear에서 계속"+ }+}diff --git a/nanobot/channels/linear/webui/locales/pt-BR.json b/nanobot/channels/linear/webui/locales/pt-BR.jsonnew file mode 100644index 000000000..caa01e3d7--- /dev/null+++ b/nanobot/channels/linear/webui/locales/pt-BR.json@@ -0,0 +1,71 @@+{+ "description": "Use o nanobot em issues do Linear por meio de Agent Sessions nativas.",+ "requirements": "Um aplicativo OAuth privado do Linear e uma URL pública HTTPS estável para callbacks",+ "setup": {+ "docsLabel": "Abrir o guia de configuração do Linear",+ "officialLabel": "Criar aplicativo OAuth do Linear",+ "tryIt": "Mencione o aplicativo em um comentário da issue. As mensagens seguintes dentro da Agent Session não precisam de outra menção.",+ "summary": "Crie um aplicativo OAuth privado do Linear, salve as credenciais e a URL pública e autorize o workspace. Cada nova sessão exige uma @menção explícita; comentários comuns são ignorados.",+ "steps": [+ "Exponha esta instância do nanobot por uma URL HTTPS estável (um túnel pode ser usado).",+ "Crie um aplicativo OAuth privado no Linear com os escopos read, write e app:mentionable. Não adicione app:assignable.",+ "Inscreva o webhook do aplicativo em AgentSessionEvent, PermissionChange e OAuthAuthorization usando a URL gerada.",+ "Salve as configurações, conecte o workspace com OAuth e @mencione o aplicativo em uma issue."+ ],+ "fields": {+ "clientId": {+ "label": "ID do cliente OAuth",+ "placeholder": "ID do cliente OAuth do Linear",+ "help": "Copie do aplicativo OAuth privado no Linear."+ },+ "clientSecret": {+ "label": "Segredo do cliente OAuth",+ "placeholder": "••••••",+ "help": "Armazenado somente nesta instância do nanobot."+ },+ "webhookSigningSecret": {+ "label": "Segredo de assinatura do webhook",+ "placeholder": "••••••",+ "help": "Usado para verificar Linear-Signature antes de interpretar o conteúdo do webhook."+ },+ "publicBaseUrl": {+ "label": "URL HTTPS pública",+ "placeholder": "https://nanobot.example.com",+ "help": "Uma origem HTTPS estável encaminhada ao listener abaixo; não inclua um caminho."+ },+ "host": {+ "label": "Host de escuta",+ "placeholder": "0.0.0.0"+ },+ "port": {+ "label": "Porta de escuta",+ "placeholder": "3979"+ },+ "webhookPath": {+ "label": "Caminho do webhook",+ "placeholder": "/linear/webhook"+ },+ "oauthCallbackPath": {+ "label": "Caminho do callback OAuth",+ "placeholder": "/linear/oauth/callback"+ },+ "allowFrom": {+ "label": "Usuários do Linear permitidos",+ "placeholder": "IDs de usuário do Linear separados por vírgulas",+ "help": "Deixe vazio para usar o pareamento do nanobot ou use * para permitir todos os usuários dos workspaces conectados."+ }+ }+ },+ "custom": {+ "qrAlt": "Código QR de autorização do Linear",+ "authorizeTitle": "Autorizar no Linear",+ "authorizeDescription": "Abra o Linear neste navegador ou escaneie o código QR. O nanobot habilitará o canal após a autorização.",+ "waiting": "Aguardando autorização do Linear...",+ "connected": "O Linear está conectado.",+ "stopped": "A autorização foi interrompida.",+ "connecting": "Conectando...",+ "reconnect": "Conectar outro workspace",+ "connect": "Conectar Linear",+ "openLinear": "Continuar no Linear"+ }+}diff --git a/nanobot/channels/linear/webui/locales/vi.json b/nanobot/channels/linear/webui/locales/vi.jsonnew file mode 100644index 000000000..9f68506d0--- /dev/null+++ b/nanobot/channels/linear/webui/locales/vi.json@@ -0,0 +1,71 @@+{+ "description": "Sử dụng nanobot từ issue Linear thông qua Agent Session gốc.",+ "requirements": "Ứng dụng OAuth Linear riêng tư và URL callback HTTPS công khai, ổn định",+ "setup": {+ "docsLabel": "Mở hướng dẫn thiết lập Linear",+ "officialLabel": "Tạo ứng dụng OAuth Linear",+ "tryIt": "Nhắc đến ứng dụng trong bình luận của issue. Tin nhắn tiếp theo trong Agent Session không cần nhắc lại.",+ "summary": "Tạo ứng dụng OAuth Linear riêng tư, lưu thông tin xác thực và URL công khai, rồi cấp quyền cho workspace. Mỗi phiên mới cần @mention rõ ràng; bình luận thông thường sẽ bị bỏ qua.",+ "steps": [+ "Công khai phiên bản nanobot này qua URL HTTPS ổn định (có thể dùng tunnel).",+ "Tạo ứng dụng OAuth riêng tư trong Linear với các scope read, write và app:mentionable. Không thêm app:assignable.",+ "Đăng ký webhook của ứng dụng cho AgentSessionEvent, PermissionChange và OAuthAuthorization bằng URL được tạo.",+ "Lưu cài đặt, kết nối workspace qua OAuth, rồi @mention ứng dụng trong một issue."+ ],+ "fields": {+ "clientId": {+ "label": "ID máy khách OAuth",+ "placeholder": "ID máy khách OAuth Linear",+ "help": "Sao chép từ ứng dụng OAuth riêng tư trong Linear."+ },+ "clientSecret": {+ "label": "Mã bí mật máy khách OAuth",+ "placeholder": "••••••",+ "help": "Chỉ được lưu trên phiên bản nanobot này."+ },+ "webhookSigningSecret": {+ "label": "Mã bí mật ký webhook",+ "placeholder": "••••••",+ "help": "Dùng để xác minh Linear-Signature trước khi phân tích nội dung webhook."+ },+ "publicBaseUrl": {+ "label": "URL HTTPS công khai",+ "placeholder": "https://nanobot.example.com",+ "help": "Origin HTTPS ổn định được chuyển tiếp tới listener bên dưới; không bao gồm path."+ },+ "host": {+ "label": "Host lắng nghe",+ "placeholder": "0.0.0.0"+ },+ "port": {+ "label": "Cổng lắng nghe",+ "placeholder": "3979"+ },+ "webhookPath": {+ "label": "Đường dẫn webhook",+ "placeholder": "/linear/webhook"+ },+ "oauthCallbackPath": {+ "label": "Đường dẫn callback OAuth",+ "placeholder": "/linear/oauth/callback"+ },+ "allowFrom": {+ "label": "Người dùng Linear được phép",+ "placeholder": "ID người dùng Linear, phân tách bằng dấu phẩy",+ "help": "Để trống để dùng ghép đôi nanobot, hoặc dùng * để cho phép mọi người dùng trong các workspace đã kết nối."+ }+ }+ },+ "custom": {+ "qrAlt": "Mã QR cấp quyền Linear",+ "authorizeTitle": "Cấp quyền trong Linear",+ "authorizeDescription": "Mở Linear trong trình duyệt này hoặc quét mã QR. nanobot sẽ bật channel sau khi được cấp quyền.",+ "waiting": "Đang chờ cấp quyền Linear...",+ "connected": "Linear đã được kết nối.",+ "stopped": "Đã dừng cấp quyền.",+ "connecting": "Đang kết nối...",+ "reconnect": "Kết nối workspace khác",+ "connect": "Kết nối Linear",+ "openLinear": "Tiếp tục trong Linear"+ }+}diff --git a/nanobot/channels/linear/webui/locales/zh-CN.json b/nanobot/channels/linear/webui/locales/zh-CN.jsonnew file mode 100644index 000000000..4326166d5--- /dev/null+++ b/nanobot/channels/linear/webui/locales/zh-CN.json@@ -0,0 +1 @@+{"description":"通过 Linear 原生 Agent Session 在 issue 中使用 nanobot。","requirements":"一个私有 Linear OAuth 应用和稳定的公网 HTTPS 回调地址","setup":{"docsLabel":"打开 Linear 配置指南","officialLabel":"创建 Linear OAuth 应用","tryIt":"在 issue 评论中 @ 应用;进入 Agent Session 后,后续对话无需重复 @。","summary":"创建私有 Linear OAuth 应用,保存凭据和公网地址,再授权工作区。新会话必须显式 @ 应用,普通评论会被忽略。","steps":["用稳定的 HTTPS 地址暴露此 nanobot 实例(可以使用隧道)。","在 Linear 创建私有 OAuth 应用,启用 read、write 和 app:mentionable;不要启用 app:assignable。","将应用 webhook 订阅 AgentSessionEvent、PermissionChange 和 OAuthAuthorization,并填写生成的 webhook 地址。","保存设置、通过 OAuth 连接工作区,然后在 issue 中 @ 应用。"],"fields":{"clientId":{"label":"OAuth Client ID","placeholder":"Linear OAuth Client ID","help":"从 Linear 私有 OAuth 应用中复制。"},"clientSecret":{"label":"OAuth Client Secret","placeholder":"••••••","help":"只保存在此 nanobot 实例中。"},"webhookSigningSecret":{"label":"Webhook 签名密钥","placeholder":"••••••","help":"在解析 webhook 内容前验证 Linear-Signature。"},"publicBaseUrl":{"label":"公网 HTTPS 地址","placeholder":"https://nanobot.example.com","help":"稳定且能转发到下方监听端口的 HTTPS 源地址,不要包含路径。"},"host":{"label":"监听地址","placeholder":"0.0.0.0"},"port":{"label":"监听端口","placeholder":"3979"},"webhookPath":{"label":"Webhook 路径","placeholder":"/linear/webhook"},"oauthCallbackPath":{"label":"OAuth 回调路径","placeholder":"/linear/oauth/callback"},"allowFrom":{"label":"允许的 Linear 用户","placeholder":"用逗号分隔 Linear 用户 ID","help":"留空使用 nanobot 配对;填写 * 允许已连接工作区内的所有用户。"}}},"custom":{"qrAlt":"Linear 授权二维码","authorizeTitle":"在 Linear 中授权","authorizeDescription":"在当前浏览器打开 Linear 或扫描二维码;授权后 nanobot 会自动启用 channel。","waiting":"正在等待 Linear 授权……","connected":"Linear 已连接。","stopped":"授权已停止。","connecting":"正在连接……","reconnect":"连接另一个工作区","connect":"连接 Linear","openLinear":"前往 Linear"}}diff --git a/nanobot/channels/linear/webui/locales/zh-TW.json b/nanobot/channels/linear/webui/locales/zh-TW.jsonnew file mode 100644index 000000000..fefe5e27a--- /dev/null+++ b/nanobot/channels/linear/webui/locales/zh-TW.json@@ -0,0 +1 @@+{"description":"透過 Linear 原生 Agent Session 在 issue 中使用 nanobot。","requirements":"一個私有 Linear OAuth 應用程式和穩定的公網 HTTPS 回呼網址","setup":{"docsLabel":"開啟 Linear 設定指南","officialLabel":"建立 Linear OAuth 應用程式","tryIt":"在 issue 評論中 @ 應用程式;進入 Agent Session 後,後續對話無需重複 @。","summary":"建立私有 Linear OAuth 應用程式,儲存憑證和公網網址,再授權工作區。新會話必須明確 @ 應用程式,普通評論會被忽略。","steps":["用穩定的 HTTPS 網址公開此 nanobot 實例(可以使用隧道)。","在 Linear 建立私有 OAuth 應用程式,啟用 read、write 和 app:mentionable;不要啟用 app:assignable。","將應用程式 webhook 訂閱 AgentSessionEvent、PermissionChange 和 OAuthAuthorization,並填入產生的 webhook 網址。","儲存設定、透過 OAuth 連接工作區,然後在 issue 中 @ 應用程式。"],"fields":{"clientId":{"label":"OAuth Client ID","placeholder":"Linear OAuth Client ID","help":"從 Linear 私有 OAuth 應用程式中複製。"},"clientSecret":{"label":"OAuth Client Secret","placeholder":"••••••","help":"只儲存在此 nanobot 實例中。"},"webhookSigningSecret":{"label":"Webhook 簽署密鑰","placeholder":"••••••","help":"在解析 webhook 內容前驗證 Linear-Signature。"},"publicBaseUrl":{"label":"公網 HTTPS 網址","placeholder":"https://nanobot.example.com","help":"穩定且能轉送到下方監聽連接埠的 HTTPS 來源網址,不要包含路徑。"},"host":{"label":"監聽位址","placeholder":"0.0.0.0"},"port":{"label":"監聽連接埠","placeholder":"3979"},"webhookPath":{"label":"Webhook 路徑","placeholder":"/linear/webhook"},"oauthCallbackPath":{"label":"OAuth 回呼路徑","placeholder":"/linear/oauth/callback"},"allowFrom":{"label":"允許的 Linear 使用者","placeholder":"以逗號分隔 Linear 使用者 ID","help":"留空使用 nanobot 配對;填寫 * 允許已連接工作區內的所有使用者。"}}},"custom":{"qrAlt":"Linear 授權 QR code","authorizeTitle":"在 Linear 中授權","authorizeDescription":"在目前瀏覽器開啟 Linear 或掃描 QR code;授權後 nanobot 會自動啟用 channel。","waiting":"正在等待 Linear 授權……","connected":"Linear 已連接。","stopped":"授權已停止。","connecting":"正在連接……","reconnect":"連接另一個工作區","connect":"連接 Linear","openLinear":"前往 Linear"}}diff --git a/tests/channels/test_channel_plugins.py b/tests/channels/test_channel_plugins.pyindex aadce9c44..c99045e58 100644--- a/tests/channels/test_channel_plugins.py+++ b/tests/channels/test_channel_plugins.py@@ -281,7 +281,18 @@ def test_channels_config_keeps_shared_delivery_defaults():@pytest.mark.parametrize("name",- ["websocket", "telegram", "discord", "slack", "email", "feishu", "matrix", "weixin", "whatsapp"],+ [+ "websocket",+ "telegram",+ "discord",+ "slack",+ "email",+ "feishu",+ "linear",+ "matrix",+ "weixin",+ "whatsapp",+ ],)def test_special_setup_validation_is_owned_by_channel_package(name: str):plugin = load_channel_package(name)@@ -292,7 +303,7 @@ def test_special_setup_validation_is_owned_by_channel_package(name: str):assert plugin.setup.validator.__module__ == f"nanobot.channels.{name}.validation"[email protected]("name", ["feishu", "weixin", "whatsapp"])[email protected]("name", ["feishu", "linear", "weixin", "whatsapp"])def test_interactive_connector_is_owned_by_channel_package(name: str):plugin = load_channel_package(name)@@ -2667,6 +2678,7 @@ def test_optional_dependency_metadata_for_enable():"dingtalk","discord","feishu",+ "linear","matrix","mochat","msteams",diff --git a/tests/channels/test_channel_setup.py b/tests/channels/test_channel_setup.pyindex 2cbb2277c..fb2a9c49e 100644--- a/tests/channels/test_channel_setup.py+++ b/tests/channels/test_channel_setup.py@@ -18,6 +18,7 @@ EXPECTED_CHANNELS = {"discord","email","feishu",+ "linear","matrix","mattermost","mochat",diff --git a/webui/src/tests/channel-locale-registry.test.ts b/webui/src/tests/channel-locale-registry.test.tsindex c1a47e4c7..5af0a9c11 100644--- a/webui/src/tests/channel-locale-registry.test.ts+++ b/webui/src/tests/channel-locale-registry.test.ts@@ -10,6 +10,7 @@ const expectedChannels = ["discord","email","feishu",+ "linear","matrix","mattermost","mochat",diff --git a/webui/src/tests/linear-channel-ui.test.ts b/webui/src/tests/linear-channel-ui.test.tsnew file mode 100644index 000000000..895f4c629--- /dev/null+++ b/webui/src/tests/linear-channel-ui.test.ts@@ -0,0 +1,37 @@+import { describe, expect, it } from "vitest";++import { linearManifestUrl } from "../../../nanobot/channels/linear/webui/LinearConnectFlow";++describe("Linear channel UI", () => {+ it("creates a private mention-only Agent app manifest with exact callback routes", () => {+ const url = new URL(+ linearManifestUrl(+ "https://nanobot.example.com",+ "/linear/webhook",+ "/linear/oauth/callback",+ ),+ );+ const manifest = JSON.parse(url.searchParams.get("manifest") ?? "{}") as {+ distribution?: string;+ oauth?: { redirect_uris?: string[] };+ webhook?: { url?: string; resourceTypes?: string[] };+ };++ expect(url.origin + url.pathname).toBe(+ "https://linear.app/settings/api/applications/new",+ );+ expect(manifest.distribution).toBe("private");+ expect(manifest.oauth?.redirect_uris).toEqual([+ "https://nanobot.example.com/linear/oauth/callback",+ ]);+ expect(manifest.webhook?.url).toBe(+ "https://nanobot.example.com/linear/webhook",+ );+ expect(manifest.webhook?.resourceTypes).toEqual([+ "AgentSessionEvent",+ "PermissionChange",+ "OAuthAuthorization",+ ]);+ expect(manifest.webhook?.resourceTypes).not.toContain("Comment");+ });+});diff --git a/webui/src/tests/settings-channels.test.tsx b/webui/src/tests/settings-channels.test.tsxindex a241bd551..a53d2239f 100644--- a/webui/src/tests/settings-channels.test.tsx+++ b/webui/src/tests/settings-channels.test.tsx@@ -31,7 +31,7 @@ function channelSetupField(}function channelSetupContract(- channel: "discord" | "email" | "feishu" | "matrix" | "qq",+ channel: "discord" | "email" | "feishu" | "linear" | "matrix" | "qq",): ChannelSetupContract {const field = (name: string,@@ -108,6 +108,22 @@ function channelSetupContract({ alternatives: [["channels.feishu.appSecret"]] },],};+ case "linear":+ return {+ fields: [+ field("clientId", "string", { required: true }),+ field("clientSecret", "secret", { required: true }),+ field("webhookSigningSecret", "secret", { required: true }),+ field("publicBaseUrl", "string", { required: true }),+ field("host", "string", { defaultValue: "0.0.0.0" }),+ field("port", "int", { defaultValue: "3979" }),+ field("webhookPath", "string", { defaultValue: "/linear/webhook" }),+ field("oauthCallbackPath", "string", {+ defaultValue: "/linear/oauth/callback",+ }),+ field("allowFrom", "list"),+ ],+ };case "matrix":return {official_url: "https://matrix.org/ecosystem/clients/",@@ -859,6 +875,103 @@ describe("Settings channels", () => {expect(await screen.findByText("Scan with Feishu")).toBeInTheDocument();});+ it("saves a Linear public URL before OAuth credentials and reveals the app manifest", async () => {+ const linearFeature = {+ name: "linear",+ display_name: "Linear",+ webui: "webui/index.tsx",+ type: "channel",+ enabled: false,+ configured: false,+ installed: true,+ ready: false,+ status: "not_enabled",+ install_supported: true,+ requires_restart: false,+ setup: channelSetupContract("linear"),+ };+ vi.stubGlobal(+ "fetch",+ vi.fn(async (input: RequestInfo | URL) => {+ const url = String(input);+ if (url === "/api/settings") return jsonResponse(settingsPayload());+ if (url === "/api/settings/cli-apps") {+ return jsonResponse({ apps: [], installed_count: 0 });+ }+ if (url === "/api/settings/mcp-presets") {+ return jsonResponse({ presets: [], installed_count: 0 });+ }+ if (url === "/api/settings/nanobot-features") {+ return jsonResponse({ features: [linearFeature], enabled_count: 0 });+ }+ return { ok: false, status: 404, json: async () => ({}) } as Response;+ }),+ );+ requestMutationMock+ .mockResolvedValueOnce({+ name: "linear",+ status: "needs_setup",+ checks: [],+ missing_fields: [+ "channels.linear.clientId",+ "channels.linear.clientSecret",+ "channels.linear.webhookSigningSecret",+ ],+ can_enable: false,+ requires_restart: false,+ message: "Missing Linear credentials.",+ })+ .mockResolvedValueOnce({+ name: "linear",+ saved: true,+ saved_keys: ["channels.linear.publicBaseUrl"],+ nanobot_features: {+ features: [{+ ...linearFeature,+ config_values: {+ "channels.linear.publicBaseUrl": "https://nanobot.example.com",+ "channels.linear.host": "0.0.0.0",+ "channels.linear.port": "3979",+ "channels.linear.webhookPath": "/linear/webhook",+ "channels.linear.oauthCallbackPath": "/linear/oauth/callback",+ },+ configured_fields: ["channels.linear.publicBaseUrl"],+ }],+ enabled_count: 0,+ requires_restart: false,+ },+ });++ renderSettingsView({ initialSection: "channels" });++ expect(await screen.findByRole("button", { name: "View Linear settings" })).toBeInTheDocument();+ fireEvent.change(screen.getByPlaceholderText("https://nanobot.example.com"), {+ target: { value: "https://nanobot.example.com" },+ });+ fireEvent.click(screen.getByRole("button", { name: "Save" }));++ await waitFor(() =>+ expect(requestMutationMock).toHaveBeenCalledWith(+ "settings.channel.configure",+ expect.objectContaining({+ name: "linear",+ values: expect.objectContaining({+ "channels.linear.publicBaseUrl": "https://nanobot.example.com",+ }),+ }),+ 150_000,+ ),+ );+ expect(+ await screen.findByText(+ "Partial settings saved. Complete the required fields before connecting.",+ ),+ ).toBeInTheDocument();+ expect(+ await screen.findByRole("button", { name: "Create prefilled Linear app" }),+ ).toBeInTheDocument();+ });+it("enables configured Feishu assistant without starting a new connect flow", async () => {const fetchMock = vi.fn(async (input: RequestInfo | URL) => {const url = String(input);