{"_id":"@abconvert-tony/openclaw-linear-agent","_rev":"4-8cf5d12516244d361813e425c193776d","name":"@abconvert-tony/openclaw-linear-agent","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"@abconvert-tony/openclaw-linear-agent","version":"0.1.0","license":"MIT","_id":"@abconvert-tony/openclaw-linear-agent@0.1.0","maintainers":[{"name":"abconvert-tony","email":"tony@abconvert.io"}],"dist":{"shasum":"b0515513d54fea3b4650fd45e8f11cea48655b62","tarball":"https://registry.npmjs.org/@abconvert-tony/openclaw-linear-agent/-/openclaw-linear-agent-0.1.0.tgz","fileCount":40,"integrity":"sha512-Y7AwHug1Kf3jVHQ6RO7eKLAonOiErGZeBkLUHgqZ8+qrlbcuiFNfMbQovxo24EobOuO/bBWG/wfBIbfR8kStZA==","signatures":[{"sig":"MEUCIBdW5OoSuuxEbtPPleVjNkuXuQEK1FcSK4XE3Jhm/W2XAiEAtSv/eSHU1vysCxRWCOgyTwo6g5SdX3BWgKTEIM2+1t4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":155302},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"1e0a72252e089e72cb94aeadf125c176f79de0fe","scripts":{"build":"tsc","release:major":"npm version major && npm publish","release:minor":"npm version minor && npm publish","release:patch":"npm version patch && npm publish","prepublishOnly":"npm run build"},"_npmUser":{"name":"abconvert-tony","email":"tony@abconvert.io"},"openclaw":{"extensions":["./dist/index.js"]},"_npmVersion":"11.10.0","description":"Linear OAuth + AgentSessionEvent webhook bridge for OpenClaw, with registered agent tools that drive the Linear session lifecycle.","directories":{},"_nodeVersion":"22.22.0","dependencies":{"@linear/sdk":"^82.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^20.19.33"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-linear-agent_0.1.0_1777449951920_0.29464564962295325","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@abconvert-tony/openclaw-linear-agent","version":"0.1.1","license":"MIT","_id":"@abconvert-tony/openclaw-linear-agent@0.1.1","maintainers":[{"name":"abconvert-tony","email":"tony@abconvert.io"}],"dist":{"shasum":"7354b5b57ee2a12828f481643857d18560194164","tarball":"https://registry.npmjs.org/@abconvert-tony/openclaw-linear-agent/-/openclaw-linear-agent-0.1.1.tgz","fileCount":40,"integrity":"sha512-uhe2X/H2n3CuTtDHDG612M6+fMN1upUJUAOXjo4apK3dcF9a3ffxR6/8saDcvHhiKMkzD25fQrVpUDqN9Z33nQ==","signatures":[{"sig":"MEQCIAZp9OoDZU2vyrdr6TAJmPq0T+8eYz+wGTSLlVELZ1dfAiB+xis3UITcn2MoPA/3uYkCBsA2UyIzWePeU2TNO3Y+ig==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":155192},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"a502e11702cc50626b7ba7fef1dc88579c2eb1bd","scripts":{"build":"tsc","release:major":"npm version major && npm publish","release:minor":"npm version minor && npm publish","release:patch":"npm version patch && npm publish","prepublishOnly":"npm run build"},"_npmUser":{"name":"abconvert-tony","email":"tony@abconvert.io"},"openclaw":{"extensions":["./dist/index.js"]},"_npmVersion":"11.10.0","description":"Linear OAuth + AgentSessionEvent webhook bridge for OpenClaw, with registered agent tools that drive the Linear session lifecycle.","directories":{},"_nodeVersion":"22.22.0","dependencies":{"@linear/sdk":"^82.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^20.19.33"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-linear-agent_0.1.1_1777450430880_0.460877221753645","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@abconvert-tony/openclaw-linear-agent","version":"0.1.2","license":"MIT","_id":"@abconvert-tony/openclaw-linear-agent@0.1.2","maintainers":[{"name":"abconvert-tony","email":"tony@abconvert.io"}],"dist":{"shasum":"5fccebfd0aa9217d864f308ee814cd81876f238c","tarball":"https://registry.npmjs.org/@abconvert-tony/openclaw-linear-agent/-/openclaw-linear-agent-0.1.2.tgz","fileCount":40,"integrity":"sha512-UaRf0jiFZOq0EW0+PUuK5xUhmvPH0NcODVZT8/KiUZgYh9C5vaOuyNKer2WRaIQQHHqugV3B3T8pHu0x4JNojA==","signatures":[{"sig":"MEYCIQC1EIlMUqrNENSWihloes+JJqqa42+XmbwS57a2L6OJ7wIhAKlIltKf9MyTKZ8pNHO8I+wu2n53o7+n3692J29CfxCZ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":157576},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"23d891ff00e0f771005728aef616d9b260ba901d","scripts":{"build":"tsc","release:major":"npm version major && npm publish","release:minor":"npm version minor && npm publish","release:patch":"npm version patch && npm publish","prepublishOnly":"npm run build"},"_npmUser":{"name":"abconvert-tony","email":"tony@abconvert.io"},"openclaw":{"extensions":["./dist/index.js"]},"_npmVersion":"11.10.0","description":"Linear OAuth + AgentSessionEvent webhook bridge for OpenClaw, with registered agent tools that drive the Linear session lifecycle.","directories":{},"_nodeVersion":"22.22.0","dependencies":{"@linear/sdk":"^82.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^20.19.33"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-linear-agent_0.1.2_1777455081907_0.1395358747302935","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@abconvert-tony/openclaw-linear-agent","version":"0.1.3","description":"Linear OAuth + AgentSessionEvent webhook bridge for OpenClaw, with registered agent tools that drive the Linear session lifecycle.","type":"module","main":"dist/index.js","types":"dist/index.d.ts","publishConfig":{"access":"public"},"scripts":{"build":"tsc","prepublishOnly":"npm run build","release:patch":"npm version patch && npm publish","release:minor":"npm version minor && npm publish","release:major":"npm version major && npm publish"},"openclaw":{"extensions":["./dist/index.js"]},"license":"MIT","devDependencies":{"@types/node":"^20.19.33","typescript":"^5.0.0"},"dependencies":{"@linear/sdk":"^82.1.0"},"gitHead":"709e249b4ecacdba0ccba05c870119ffc7ada81c","_id":"@abconvert-tony/openclaw-linear-agent@0.1.3","_nodeVersion":"22.22.0","_npmVersion":"11.10.0","dist":{"integrity":"sha512-SmPucytvaz9/1060VXrWuUOpRBKADbOuuJwP3IREzX9d4LU9Phz5PW2aFFvt4ptKP/rgBlg4/uCDli9r2JBB7Q==","shasum":"f90d5943dc1cdd413c6804434b6f467dc1f5e9c8","tarball":"https://registry.npmjs.org/@abconvert-tony/openclaw-linear-agent/-/openclaw-linear-agent-0.1.3.tgz","fileCount":40,"unpackedSize":158584,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAOZO2xJyQYKaOMvktzkMRJ+Z/cPTxzTUNjtFfG3A0gwAiBBByqZz7aRRXv1nTSvoWlNZqQJ9/jXZci33mTlWVTAdA=="}]},"_npmUser":{"name":"abconvert-tony","email":"tony@abconvert.io"},"directories":{},"maintainers":[{"name":"abconvert-tony","email":"tony@abconvert.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openclaw-linear-agent_0.1.3_1777456054788_0.10959353210845468"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-29T08:05:51.725Z","modified":"2026-04-29T09:47:35.067Z","0.1.0":"2026-04-29T08:05:52.063Z","0.1.1":"2026-04-29T08:13:51.013Z","0.1.2":"2026-04-29T09:31:22.056Z","0.1.3":"2026-04-29T09:47:34.952Z"},"license":"MIT","description":"Linear OAuth + AgentSessionEvent webhook bridge for OpenClaw, with registered agent tools that drive the Linear session lifecycle.","maintainers":[{"name":"abconvert-tony","email":"tony@abconvert.io"}],"readme":"# linear-agent\n\nOpenClaw plugin that bridges a Linear OAuth app to a local OpenClaw agent.\nReceives `AgentSessionEvent` webhooks, dispatches the prompt to a configured\nOpenClaw agent, and exposes a small set of `registerTool` factories so the\nagent drives the Linear session lifecycle directly (final reply, error,\nelicitation, external URL attachment).\n\n## Routes\n\nThe plugin registers three HTTP routes under `/linear-agent` on your local\ngateway. Externally they sit behind whatever ingress you use (Tailscale Funnel,\nCloudflare Tunnel, ngrok, raw reverse proxy, etc.); we'll call that base URL\n`` below. If that ingress namespaces users with a path prefix\n(shared host, `//*`), include it as `` everywhere — leave it\nempty if you have your own host.\n\n| Method | Path | Purpose |\n|--------|-------------------------------------------------|-----------------------------------------------|\n| GET | `//linear-agent/connect` | Kick off Linear OAuth (`actor=app`) |\n| GET | `//linear-agent/callback` | Exchange code for tokens, persist to disk |\n| POST | `//linear-agent` | `AgentSessionEvent` receiver (HMAC verified) |\n\nThe plugin itself only sees `/linear-agent/...` — the ingress is responsible\nfor stripping `` before forwarding. The same `` (or its\nabsence) must appear in **all three places** — the Linear app's Redirect URI,\nthe Linear app's Webhook URL, and the `linearRedirectUri` plugin config — and\nmust match byte-for-byte. A mismatch on the redirect URI surfaces as Linear's\n*\"Invalid redirect_uri parameter for the application\"* error.\n\nThe ingress must also forward both `/.../linear-agent` and `/.../linear-agent/`\n(with and without trailing slash) to the gateway. Linear normalizes some\ndelivery URLs with a trailing slash; if your reverse proxy only matches the\nno-slash form, webhooks return `404` from the proxy and never reach the plugin.\n\n## Agent-callable tools\n\nRegistered via `api.registerTool`. They auto-appear only on agent runs that\noriginated from a Linear webhook (i.e. when a Linear session is bound to the\nactive `sessionKey`).\n\n| Tool | Maps to | Use |\n|------|---------|-----|\n| `linear_post_thought` | `AgentActivityCreateInput { type: \"thought\" }` | Non-terminal: mid-run narration. Set `ephemeral: true` for fleeting status that the next activity replaces |\n| `linear_post_action` | `AgentActivityActionContent { action, parameter, result? }` | Non-terminal: structured \"action\" card. Post once without `result` to announce work-in-progress, then again with the same `action`+`parameter` and a filled-in `result` when done |\n| `linear_post_comment` | `CommentCreateInput { body, issueId, parentId? }` | Non-terminal: post a real Linear comment (visible in the issue thread, not just the agent panel). Defaults to threading under the comment that triggered this turn; pass `threadUnderSourceComment: false` for a top-level issue comment |\n| `linear_post_response` | `AgentActivityCreateInput { type: \"response\" }` | Terminal: the agent's final reply for this turn |\n| `linear_post_error` | `AgentActivityCreateInput { type: \"error\" }` | Terminal: surface a failure to the requester |\n| `linear_post_elicitation` | `AgentActivityCreateInput { type: \"elicitation\" }` | Terminal: pause and ask the user for more info |\n| `linear_update_issue` | `IssueUpdateInput` (subset) | Update state, assignee/delegate, priority, labels, title/description, due date. `stateType` resolves to a stateId via the team's workflow states; `issueId` defaults to the bound issue |\n| `linear_set_session_plan` | `AgentSessionUpdateInput.plan` | Replace the agent's plan checklist for this session; each step has `content` and `status: pending\\|inProgress\\|completed\\|canceled` |\n| `linear_attach_external_url` | `AgentSessionUpdateInput.addedExternalUrls` | Attach a PR/preview/dashboard URL; Linear renders it as a session button and tracks downstream updates |\n\n## Prerequisites\n\n- A running OpenClaw gateway (see the [OpenClaw docs](https://docs.openclaw.ai))\n with an agent in `agents.list[]` ready to handle Linear events.\n- A public ingress for that gateway (Tailscale Funnel, Cloudflare Tunnel, ngrok,\n reverse proxy, etc.) — Linear webhooks and the OAuth callback both need a\n reachable URL.\n\n## Setup\n\n### 1. Register a Linear OAuth application\n\nLinear → *Settings* → *API* → *OAuth applications* → *New application*.\n\n> **Decide your `` first.** If your ingress namespaces users with a\n> path (e.g. `https://shared.example.com/jacklyn/*` → her gateway), the prefix\n> is `/jacklyn` and every URL below must include it. On the shared abconvert\n> host (`abconvert-spark.tailc2b7f2.ts.net`) the prefix is your own first name\n> (`/tony`, `/jacklyn`, …) — the segment that routes traffic to your gateway.\n> If you have your own host, leave the prefix empty. The Redirect URI you\n> register here, the Webhook URL, and the `linearRedirectUri` in step 2 must\n> all match exactly.\n\n- **Redirect URI:** `//linear-agent/callback`\n (e.g. `https://abconvert-spark.tailc2b7f2.ts.net/jacklyn/linear-agent/callback`)\n- **Webhook URL:** `//linear-agent`\n (e.g. `https://abconvert-spark.tailc2b7f2.ts.net/jacklyn/linear-agent`)\n- Enable webhooks; subscribe to **Agent session events**\n- **Allowed scopes:** must be a superset of whatever you set in\n `linearScopes` later. The default `linearScopes` is\n `read,write,app:assignable,app:mentionable`; if the Linear app isn't\n configured with `app:assignable` and `app:mentionable`, OAuth silently\n grants fewer scopes and `delegateOnCreate` later fails.\n- Copy the client id, client secret, and webhook signing secret\n\nAdmin permissions on the workspace are required to install with `actor=app`.\n\nMake sure your ingress proxies both `//linear-agent` and\n`//linear-agent/` (trailing slash) to the gateway. Linear sometimes\ndelivers webhooks to the trailing-slash form; if the proxy only matches one,\nthose deliveries return `404` from the proxy and never reach the plugin. Quick\ncheck: `curl -i -X POST //linear-agent/` should return\n`401 Unauthorized` from the plugin (good — handler reachable), not `404` from\nthe proxy.\n\n### 2. Configure the plugin\n\nEdit `~/.openclaw/openclaw.json` and set `plugins.entries.linear-agent.config`:\n\n```json\n{\n \"plugins\": {\n \"allow\": [\"linear-agent\"],\n \"entries\": {\n \"linear-agent\": {\n \"enabled\": true,\n \"config\": {\n \"agentId\": \"dev\",\n \"linearClientId\": \"${LINEAR_CLIENT_ID}\",\n \"linearClientSecret\": \"${LINEAR_CLIENT_SECRET}\",\n \"linearWebhookSecret\": \"${LINEAR_WEBHOOK_SECRET}\",\n \"linearRedirectUri\": \"//linear-agent/callback\"\n }\n }\n }\n }\n}\n```\n\n`${ENV_VAR}` interpolation is supported — keep secrets in `~/.openclaw/.env`\nrather than the JSON.\n\nThe `agentId` here must match the `id` of an entry in `agents.list[]` — that's\nthe OpenClaw agent the plugin will dispatch Linear events to. Step 2b uses the\nsame id.\n\nOptional config keys: `linearScopes` (default `read,write,app:assignable,app:mentionable`),\n`linearTokenStorePath` (default `~/.openclaw/workspace/.pi/linear-agent-tokens.json`),\n`historyLimit` (default 20), `startOnCreate`, `delegateOnCreate`,\n`strictAddressing` + `mentionHandle` (only run prompted events that explicitly\n@-mention the agent; useful when humans and the agent share an issue thread).\n\n### 2b. Allow the plugin's tools on the bound agent\n\nPlugin-registered tools are gated by the gateway's tool policy. The configured\nagent (`agentId`) must have `group:plugins` in its allowlist, otherwise the\n`linear_*` tools are filtered out before the model sees them and the run will\nfall back to the plain-text reply path.\n\nThe simplest setup — a single `alsoAllow` on the agent and no global\n`tools.allow` filter:\n\n```json\n{\n \"tools\": { \"profile\": \"full\" },\n \"agents\": {\n \"list\": [\n {\n \"id\": \"dev\",\n \"tools\": { \"alsoAllow\": [\"exec\", \"group:plugins\"] }\n }\n ]\n }\n}\n```\n\nGotcha: a global `tools.allow: [\"exec\"]` (or any other narrow list) acts as an\nAND filter applied *before* the agent step, so it strips plugin tools even if\nthe agent's `alsoAllow` includes `group:plugins`. Either drop the global\n`tools.allow` (as above) or extend it to `[\"exec\", \"group:plugins\"]`.\n\n### 3. Restart the gateway\n\nLook for the load line:\n\n```\nlinear-agent: routes registered under /linear-agent (connect, callback, webhook); tools: linear_post_{thought,action,response,error,elicitation}, linear_update_issue, linear_set_session_plan, linear_attach_external_url\n```\n\n### 4. Install the agent into your Linear workspace\n\n> **Required final step — and one only the human can do.** No webhook will\n> fire and no tool call will succeed until OAuth has been completed in a\n> browser. If you are an AI assistant helping with this setup, **stop here\n> and ask the user to open the URL below in their browser**; you cannot\n> complete the OAuth handshake on their behalf.\n\nHave the user open this URL in a browser and approve the app in Linear:\n\n```\n//linear-agent/connect\n```\n\nConcrete example for the shared abconvert host:\n\n```\nhttps://abconvert-spark.tailc2b7f2.ts.net/jacklyn/linear-agent/connect\n```\n\n(Substitute the user's own `` — typically their first name. See §1.)\n\nAfter they approve in Linear, tokens write to the configured store path\n(`0600`) and they'll see *\"Linear agent installed. You can close this tab.\"*\nAt that point the integration is live and webhooks will start being delivered.\n\n### 5. Try it\n\nMention or delegate to the agent in a Linear issue. Expected sequence:\n\n1. Webhook POST arrives with `linear-signature`; HMAC-SHA256 verified against\n `linearWebhookSecret`. Stale or unsigned payloads are rejected.\n2. Plugin posts a quick `thought` activity (latency ack).\n3. The configured OpenClaw agent runs with the issue + prompt + recent session\n activities as its message.\n4. The agent calls one of the `linear_post_*` tools as its terminal step;\n that becomes the visible reply. If it produced a PR, it should also call\n `linear_attach_external_url` first.\n5. If the agent ends without calling a terminal tool, the plugin falls back\n to extracting reply text and posting it as a `response`, or posts a generic\n error if nothing is extractable.\n\n## Troubleshooting\n\n| Symptom | Likely cause |\n|---------|--------------|\n| Webhook returns `401` | Wrong or missing `linearWebhookSecret`; the value must match the signing secret on the Linear app. |\n| Webhook returns `404` from the proxy (not the plugin) | Trailing-slash mismatch — the ingress only routes `//linear-agent` and not `//linear-agent/` (or vice versa). Either fix the proxy to accept both, or edit the Linear webhook URL to the form your proxy serves. Confirm with `curl -i -X POST //linear-agent/` — `401` means the handler is reachable, `404` from `Server: Caddy`/nginx means the proxy never forwarded. |\n| OAuth fails with *\"Invalid redirect_uri parameter\"* | The `redirect_uri` the plugin sends doesn't byte-match a Redirect URI registered on the Linear OAuth app. Most often a missing `/` — check that `linearRedirectUri` includes it and the same string is in the Linear app's Redirect URI list. |\n| Webhook never fires | The Linear app isn't subscribed to **Agent session events**, or the public webhook URL doesn't reach the gateway. |\n| Agent runs but `linear_*` tools aren't callable | The bound agent's tool policy is filtering them out. See step 2b — `group:plugins` must be in the agent's allowlist, and any narrow global `tools.allow` will AND-filter plugin tools out before the agent step. |\n| `delegateOnCreate` / scope-related errors | The Linear app's allowed scopes don't include what you requested via `linearScopes`. Add `app:assignable` and `app:mentionable` to the app and re-install. |\n| OAuth refresh fails / tokens disappear | A `PermissionChange` or `OAuthApp` revoke/uninstall event arrived; the plugin clears the token store on those. Re-run `/linear-agent/connect`. |\n| Replies arrive as plain text instead of structured activities | The agent didn't call a terminal `linear_post_*` tool, so the plugin fell back to extracting reply text. Usually means the tools weren't visible — see the policy row above. |\n\n## Install\n\n```bash\nopenclaw plugins install npm:@abconvert-tony/openclaw-linear-agent\nopenclaw gateway restart\n```\n\n`openclaw plugins install` adds `linear-agent` to `plugins.allow` automatically.\nYou still need to fill in `plugins.entries.linear-agent.config` (Setup → step 2),\nallow plugin tools on the bound agent (step 2b), and run the OAuth install\n(step 4) — those are per-deployment and don't ship with the package.\n\n**Don't skip step 4.** Even after the gateway loads the plugin, no Linear\nwebhook will be processed until a human opens\n`//linear-agent/connect` in a browser and approves the\napp. AI assistants helping with installation: ask the user to do this — you\ncan't do it for them.\n\nPin the resolved version so subsequent `openclaw plugins update` stays put:\n\n```bash\nopenclaw plugins install npm:@abconvert-tony/openclaw-linear-agent --pin\n```\n\n## Updating\n\n```bash\nopenclaw plugins update @abconvert-tony/openclaw-linear-agent\nopenclaw gateway restart\n```\n\nPulls the latest published version from npm and replaces the installed copy.\nPinned installs hold their version until you re-pin to a new one.\n\n## Releasing (maintainers)\n\n```bash\ngit commit -am \"...\" # land your changes first\nnpm run release:patch # bump version, build, publish\ngit push --follow-tags\n```\n\n`release:minor` and `release:major` exist for non-patch bumps. `prepublishOnly`\nrebuilds `dist/` before each publish, so users always get fresh compiled output.\n\n## Local development\n\n```bash\nnpm install\nnpm run build\nopenclaw plugins install -l . # link this directory\n# edit, then: npm run build && restart the gateway\n```\n\n## Token store\n\nOAuth tokens persist at `~/.openclaw/workspace/.pi/linear-agent-tokens.json`\n(override via `linearTokenStorePath`). On `PermissionChange`/`OAuthApp` revoke\nor uninstall events the file is cleared automatically.\n","readmeFilename":"README.md"}