switchroom 0.15.11 → 0.15.12

package/dist/host-control/main.js

@@ -13882,6 +13882,11 @@ var TelegramChannelSchema = exports_external.object({
   }).optional().describe("Per-source rate limit for the webhook ingest path (#714). " + "Off by default — when this key is absent the handler skips " + "rate-limit checks entirely. Opt in by setting `rpm` to an " + "integer requests-per-minute (token bucket per (agent, source); " + "burst equal to rpm). When enabled, exceeding the limit returns " + "429 with Retry-After header; first throttle event per " + "(agent, source) per 60s window is written to " + "<agent>/telegram/issues.jsonl. " + "Cascades from defaults.channels.telegram.webhook_rate_limit."),
   webhook_via_gateway: exports_external.boolean().optional().describe("Route verified webhook events to the agent's in-container gateway " + "over a peercred-gated UDS (<agent>/telegram/webhook.sock) instead " + "of having the host-side web receiver write the agent dir directly. " + "Required under the Docker runtime: the receiver runs as the host " + "operator UID and cannot write the per-agent-UID-owned agent dir " + "(EACCES 500) nor connect the gateway socket. When true the gateway " + "(running as the agent UID) becomes the sole writer of " + "webhook-events.jsonl + dedup/cooldown state and also fires " + "webhook_dispatch. Off by default for back-compat with host-runtime " + "installs. See docs/rfcs/webhook-via-gateway-socket.md."),
   webhook_require_edge: exports_external.boolean().optional().describe("Cloudflare-only edge lock: require the X-Switchroom-Edge header " + "(injected by a Cloudflare Transform Rule on hooks.switchroom.ai) to " + "match the operator's edge secret at ~/.switchroom/webhook-edge-secret " + "before any HMAC verification; reject 403 otherwise. Proves the " + "request entered through our Cloudflare edge — the per-agent HMAC " + "alone can't (it proves body provenance, not network path). Stacks " + "on the GitHub-IP WAF + per-agent HMAC. Fail-closed: when required " + "but the secret file is missing/empty every request is rejected. Off " + "by default. See docs/rfcs/webhook-cloudflare-edge-lock.md."),
+  linear_agent: exports_external.object({
+    enabled: exports_external.boolean(),
+    token: exports_external.string().describe("vault:<key> reference to the Linear OAuth app token (actor=app). " + "Resolved at runtime via the vault broker (canonically " + "vault:linear/<agent>/token). Never an inline literal."),
+    workspace_id: exports_external.string().optional().describe("Optional Linear workspace (organization) id this agent is " + "installed into. Informational — used for setup hints and " + "multi-workspace disambiguation; the token already scopes the " + "app to its workspace.")
+  }).optional().describe("Linear first-class agent integration (#2298). When enabled, the " + "agent appears in a Linear workspace as an app actor (own name/" + "avatar, @-mentionable, delegate-assignable). Linear AgentSessionEvent " + "webhooks (mention / delegation) wake the agent instantly via the " + "same gateway inject path as webhook_dispatch, tagged " + 'meta.source="linear" with the agent_session_id, and the agent ' + "responds with structured AgentActivity (thought/message/complete/" + "error) via the linear_agent_activity MCP tool. Builds the " + "session-lifecycle layer on top of the plain webhook_sources:[linear] " + "+ webhook_dispatch support (#2272). The OAuth app token is stored in " + "the vault and referenced here as vault:linear/<agent>/token; run " + "`switchroom linear-agent setup <agent>` to provision it. Off by " + "default — opt in per agent. Cascades from " + "defaults.channels.telegram.linear_agent."),
   chat_id: exports_external.string().regex(/^-\d+$/, 'supergroup chat_id must be a negative integer as a string (e.g. "-1001234567890")').optional().describe("Per-agent supergroup ID — overrides fleet `telegram.forum_chat_id`. " + "When set, requires `default_topic_id`. Negative integer as string. " + "Forbidden when `dm_only: true`. See docs/rfcs/supergroup-mode.md."),
   default_topic_id: exports_external.number().int().positive().optional().describe("Forum topic ID this agent's automated outbounds default to when " + "no more-specific alias resolves. Defaults to General (topic 1) when " + "`chat_id` is set and this is omitted — set it only to pin a different " + "fallback topic. " + "Telegram's General topic is `id=1` at MTProto but sends omit the " + "field — the outbound wrapper strips `message_thread_id === 1` " + "on send. Forbidden when `dm_only: true`."),
   topic_aliases: exports_external.record(exports_external.string(), exports_external.number().int().positive()).optional().describe("Operator-friendly names for forum topic IDs (e.g. " + "`{ general: 1, planning: 17, cron: 23, admin: 31, alerts: 41 }`). " + "Referenced from per-cron `topic:` fields and the outbound router " + "for autonomous events (boot → alerts, hostd → admin, etc.). " + "Cascades per-key through defaults → profile → agent.")

package/dist/vault/approvals/kernel-server.js

@@ -11480,6 +11480,11 @@ var init_schema = __esm(() => {
     }).optional().describe("Per-source rate limit for the webhook ingest path (#714). " + "Off by default — when this key is absent the handler skips " + "rate-limit checks entirely. Opt in by setting `rpm` to an " + "integer requests-per-minute (token bucket per (agent, source); " + "burst equal to rpm). When enabled, exceeding the limit returns " + "429 with Retry-After header; first throttle event per " + "(agent, source) per 60s window is written to " + "<agent>/telegram/issues.jsonl. " + "Cascades from defaults.channels.telegram.webhook_rate_limit."),
     webhook_via_gateway: exports_external.boolean().optional().describe("Route verified webhook events to the agent's in-container gateway " + "over a peercred-gated UDS (<agent>/telegram/webhook.sock) instead " + "of having the host-side web receiver write the agent dir directly. " + "Required under the Docker runtime: the receiver runs as the host " + "operator UID and cannot write the per-agent-UID-owned agent dir " + "(EACCES 500) nor connect the gateway socket. When true the gateway " + "(running as the agent UID) becomes the sole writer of " + "webhook-events.jsonl + dedup/cooldown state and also fires " + "webhook_dispatch. Off by default for back-compat with host-runtime " + "installs. See docs/rfcs/webhook-via-gateway-socket.md."),
     webhook_require_edge: exports_external.boolean().optional().describe("Cloudflare-only edge lock: require the X-Switchroom-Edge header " + "(injected by a Cloudflare Transform Rule on hooks.switchroom.ai) to " + "match the operator's edge secret at ~/.switchroom/webhook-edge-secret " + "before any HMAC verification; reject 403 otherwise. Proves the " + "request entered through our Cloudflare edge — the per-agent HMAC " + "alone can't (it proves body provenance, not network path). Stacks " + "on the GitHub-IP WAF + per-agent HMAC. Fail-closed: when required " + "but the secret file is missing/empty every request is rejected. Off " + "by default. See docs/rfcs/webhook-cloudflare-edge-lock.md."),
+    linear_agent: exports_external.object({
+      enabled: exports_external.boolean(),
+      token: exports_external.string().describe("vault:<key> reference to the Linear OAuth app token (actor=app). " + "Resolved at runtime via the vault broker (canonically " + "vault:linear/<agent>/token). Never an inline literal."),
+      workspace_id: exports_external.string().optional().describe("Optional Linear workspace (organization) id this agent is " + "installed into. Informational — used for setup hints and " + "multi-workspace disambiguation; the token already scopes the " + "app to its workspace.")
+    }).optional().describe("Linear first-class agent integration (#2298). When enabled, the " + "agent appears in a Linear workspace as an app actor (own name/" + "avatar, @-mentionable, delegate-assignable). Linear AgentSessionEvent " + "webhooks (mention / delegation) wake the agent instantly via the " + "same gateway inject path as webhook_dispatch, tagged " + 'meta.source="linear" with the agent_session_id, and the agent ' + "responds with structured AgentActivity (thought/message/complete/" + "error) via the linear_agent_activity MCP tool. Builds the " + "session-lifecycle layer on top of the plain webhook_sources:[linear] " + "+ webhook_dispatch support (#2272). The OAuth app token is stored in " + "the vault and referenced here as vault:linear/<agent>/token; run " + "`switchroom linear-agent setup <agent>` to provision it. Off by " + "default — opt in per agent. Cascades from " + "defaults.channels.telegram.linear_agent."),
     chat_id: exports_external.string().regex(/^-\d+$/, 'supergroup chat_id must be a negative integer as a string (e.g. "-1001234567890")').optional().describe("Per-agent supergroup ID — overrides fleet `telegram.forum_chat_id`. " + "When set, requires `default_topic_id`. Negative integer as string. " + "Forbidden when `dm_only: true`. See docs/rfcs/supergroup-mode.md."),
     default_topic_id: exports_external.number().int().positive().optional().describe("Forum topic ID this agent's automated outbounds default to when " + "no more-specific alias resolves. Defaults to General (topic 1) when " + "`chat_id` is set and this is omitted — set it only to pin a different " + "fallback topic. " + "Telegram's General topic is `id=1` at MTProto but sends omit the " + "field — the outbound wrapper strips `message_thread_id === 1` " + "on send. Forbidden when `dm_only: true`."),
     topic_aliases: exports_external.record(exports_external.string(), exports_external.number().int().positive()).optional().describe("Operator-friendly names for forum topic IDs (e.g. " + "`{ general: 1, planning: 17, cron: 23, admin: 31, alerts: 41 }`). " + "Referenced from per-cron `topic:` fields and the outbound router " + "for autonomous events (boot → alerts, hostd → admin, etc.). " + "Cascades per-key through defaults → profile → agent.")

package/dist/vault/broker/server.js

@@ -11480,6 +11480,11 @@ var init_schema = __esm(() => {
     }).optional().describe("Per-source rate limit for the webhook ingest path (#714). " + "Off by default — when this key is absent the handler skips " + "rate-limit checks entirely. Opt in by setting `rpm` to an " + "integer requests-per-minute (token bucket per (agent, source); " + "burst equal to rpm). When enabled, exceeding the limit returns " + "429 with Retry-After header; first throttle event per " + "(agent, source) per 60s window is written to " + "<agent>/telegram/issues.jsonl. " + "Cascades from defaults.channels.telegram.webhook_rate_limit."),
     webhook_via_gateway: exports_external.boolean().optional().describe("Route verified webhook events to the agent's in-container gateway " + "over a peercred-gated UDS (<agent>/telegram/webhook.sock) instead " + "of having the host-side web receiver write the agent dir directly. " + "Required under the Docker runtime: the receiver runs as the host " + "operator UID and cannot write the per-agent-UID-owned agent dir " + "(EACCES 500) nor connect the gateway socket. When true the gateway " + "(running as the agent UID) becomes the sole writer of " + "webhook-events.jsonl + dedup/cooldown state and also fires " + "webhook_dispatch. Off by default for back-compat with host-runtime " + "installs. See docs/rfcs/webhook-via-gateway-socket.md."),
     webhook_require_edge: exports_external.boolean().optional().describe("Cloudflare-only edge lock: require the X-Switchroom-Edge header " + "(injected by a Cloudflare Transform Rule on hooks.switchroom.ai) to " + "match the operator's edge secret at ~/.switchroom/webhook-edge-secret " + "before any HMAC verification; reject 403 otherwise. Proves the " + "request entered through our Cloudflare edge — the per-agent HMAC " + "alone can't (it proves body provenance, not network path). Stacks " + "on the GitHub-IP WAF + per-agent HMAC. Fail-closed: when required " + "but the secret file is missing/empty every request is rejected. Off " + "by default. See docs/rfcs/webhook-cloudflare-edge-lock.md."),
+    linear_agent: exports_external.object({
+      enabled: exports_external.boolean(),
+      token: exports_external.string().describe("vault:<key> reference to the Linear OAuth app token (actor=app). " + "Resolved at runtime via the vault broker (canonically " + "vault:linear/<agent>/token). Never an inline literal."),
+      workspace_id: exports_external.string().optional().describe("Optional Linear workspace (organization) id this agent is " + "installed into. Informational — used for setup hints and " + "multi-workspace disambiguation; the token already scopes the " + "app to its workspace.")
+    }).optional().describe("Linear first-class agent integration (#2298). When enabled, the " + "agent appears in a Linear workspace as an app actor (own name/" + "avatar, @-mentionable, delegate-assignable). Linear AgentSessionEvent " + "webhooks (mention / delegation) wake the agent instantly via the " + "same gateway inject path as webhook_dispatch, tagged " + 'meta.source="linear" with the agent_session_id, and the agent ' + "responds with structured AgentActivity (thought/message/complete/" + "error) via the linear_agent_activity MCP tool. Builds the " + "session-lifecycle layer on top of the plain webhook_sources:[linear] " + "+ webhook_dispatch support (#2272). The OAuth app token is stored in " + "the vault and referenced here as vault:linear/<agent>/token; run " + "`switchroom linear-agent setup <agent>` to provision it. Off by " + "default — opt in per agent. Cascades from " + "defaults.channels.telegram.linear_agent."),
     chat_id: exports_external.string().regex(/^-\d+$/, 'supergroup chat_id must be a negative integer as a string (e.g. "-1001234567890")').optional().describe("Per-agent supergroup ID — overrides fleet `telegram.forum_chat_id`. " + "When set, requires `default_topic_id`. Negative integer as string. " + "Forbidden when `dm_only: true`. See docs/rfcs/supergroup-mode.md."),
     default_topic_id: exports_external.number().int().positive().optional().describe("Forum topic ID this agent's automated outbounds default to when " + "no more-specific alias resolves. Defaults to General (topic 1) when " + "`chat_id` is set and this is omitted — set it only to pin a different " + "fallback topic. " + "Telegram's General topic is `id=1` at MTProto but sends omit the " + "field — the outbound wrapper strips `message_thread_id === 1` " + "on send. Forbidden when `dm_only: true`."),
     topic_aliases: exports_external.record(exports_external.string(), exports_external.number().int().positive()).optional().describe("Operator-friendly names for forum topic IDs (e.g. " + "`{ general: 1, planning: 17, cron: 23, admin: 31, alerts: 41 }`). " + "Referenced from per-cron `topic:` fields and the outbound router " + "for autonomous events (boot → alerts, hostd → admin, etc.). " + "Cascades per-key through defaults → profile → agent.")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.15.11",
+  "version": "0.15.12",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/bridge/bridge.ts

@@ -455,6 +455,30 @@ const TOOL_SCHEMAS = [
       required: ['chat_id', 'key'],
     },
   },
+  {
+    name: 'linear_agent_activity',
+    description:
+      'Emit a structured Linear AgentActivity against an agent session (#2298). Use this ONLY inside a turn that was woken by a Linear agent session (the inbound carries meta.source="linear" and meta.agent_session_id) — pass that agent_session_id back here. Linear renders activities as status chips + a timeline on the issue, so the human sees acknowledge → work → result. Emit a `thought` within ~10s of being woken so the session does not look dead, then `message`(s) as you make progress, and finally exactly one terminal `complete` (work done) or `error` (you could not proceed). body is required for thought/message/error and optional for complete. Resolves the agent\'s Linear app token from the vault; on VAULT-BROKER-DENIED it returns an error instructing you to vault_request_access for `linear/<agent>/token`.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        agent_session_id: {
+          type: 'string',
+          description: 'The Linear AgentSession id — copy it verbatim from the woken turn\'s meta.agent_session_id.',
+        },
+        type: {
+          type: 'string',
+          enum: ['thought', 'message', 'complete', 'error'],
+          description: 'Activity kind. thought = visible reasoning ack (emit within ~10s); message = progress update; complete = terminal success; error = terminal failure.',
+        },
+        body: {
+          type: 'string',
+          description: 'Activity text (Markdown). Required for thought/message/error; optional for complete (a closing summary).',
+        },
+      },
+      required: ['agent_session_id', 'type'],
+    },
+  },
 ]
 
 mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_SCHEMAS }))

package/telegram-plugin/dist/bridge/bridge.js

@@ -24934,6 +24934,29 @@ var TOOL_SCHEMAS = [
       },
       required: ["chat_id", "key"]
     }
+  },
+  {
+    name: "linear_agent_activity",
+    description: 'Emit a structured Linear AgentActivity against an agent session (#2298). Use this ONLY inside a turn that was woken by a Linear agent session (the inbound carries meta.source="linear" and meta.agent_session_id) \u2014 pass that agent_session_id back here. Linear renders activities as status chips + a timeline on the issue, so the human sees acknowledge \u2192 work \u2192 result. Emit a `thought` within ~10s of being woken so the session does not look dead, then `message`(s) as you make progress, and finally exactly one terminal `complete` (work done) or `error` (you could not proceed). body is required for thought/message/error and optional for complete. Resolves the agent\'s Linear app token from the vault; on VAULT-BROKER-DENIED it returns an error instructing you to vault_request_access for `linear/<agent>/token`.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        agent_session_id: {
+          type: "string",
+          description: "The Linear AgentSession id \u2014 copy it verbatim from the woken turn's meta.agent_session_id."
+        },
+        type: {
+          type: "string",
+          enum: ["thought", "message", "complete", "error"],
+          description: "Activity kind. thought = visible reasoning ack (emit within ~10s); message = progress update; complete = terminal success; error = terminal failure."
+        },
+        body: {
+          type: "string",
+          description: "Activity text (Markdown). Required for thought/message/error; optional for complete (a closing summary)."
+        }
+      },
+      required: ["agent_session_id", "type"]
+    }
   }
 ];
 mcp.setRequestHandler(ListToolsRequestSchema2, async () => ({ tools: TOOL_SCHEMAS }));

package/telegram-plugin/dist/gateway/gateway.js

@@ -23993,6 +23993,11 @@ var init_schema = __esm(() => {
     }).optional().describe("Per-source rate limit for the webhook ingest path (#714). " + "Off by default \u2014 when this key is absent the handler skips " + "rate-limit checks entirely. Opt in by setting `rpm` to an " + "integer requests-per-minute (token bucket per (agent, source); " + "burst equal to rpm). When enabled, exceeding the limit returns " + "429 with Retry-After header; first throttle event per " + "(agent, source) per 60s window is written to " + "<agent>/telegram/issues.jsonl. " + "Cascades from defaults.channels.telegram.webhook_rate_limit."),
     webhook_via_gateway: exports_external.boolean().optional().describe("Route verified webhook events to the agent's in-container gateway " + "over a peercred-gated UDS (<agent>/telegram/webhook.sock) instead " + "of having the host-side web receiver write the agent dir directly. " + "Required under the Docker runtime: the receiver runs as the host " + "operator UID and cannot write the per-agent-UID-owned agent dir " + "(EACCES 500) nor connect the gateway socket. When true the gateway " + "(running as the agent UID) becomes the sole writer of " + "webhook-events.jsonl + dedup/cooldown state and also fires " + "webhook_dispatch. Off by default for back-compat with host-runtime " + "installs. See docs/rfcs/webhook-via-gateway-socket.md."),
     webhook_require_edge: exports_external.boolean().optional().describe("Cloudflare-only edge lock: require the X-Switchroom-Edge header " + "(injected by a Cloudflare Transform Rule on hooks.switchroom.ai) to " + "match the operator's edge secret at ~/.switchroom/webhook-edge-secret " + "before any HMAC verification; reject 403 otherwise. Proves the " + "request entered through our Cloudflare edge \u2014 the per-agent HMAC " + "alone can't (it proves body provenance, not network path). Stacks " + "on the GitHub-IP WAF + per-agent HMAC. Fail-closed: when required " + "but the secret file is missing/empty every request is rejected. Off " + "by default. See docs/rfcs/webhook-cloudflare-edge-lock.md."),
+    linear_agent: exports_external.object({
+      enabled: exports_external.boolean(),
+      token: exports_external.string().describe("vault:<key> reference to the Linear OAuth app token (actor=app). " + "Resolved at runtime via the vault broker (canonically " + "vault:linear/<agent>/token). Never an inline literal."),
+      workspace_id: exports_external.string().optional().describe("Optional Linear workspace (organization) id this agent is " + "installed into. Informational \u2014 used for setup hints and " + "multi-workspace disambiguation; the token already scopes the " + "app to its workspace.")
+    }).optional().describe("Linear first-class agent integration (#2298). When enabled, the " + "agent appears in a Linear workspace as an app actor (own name/" + "avatar, @-mentionable, delegate-assignable). Linear AgentSessionEvent " + "webhooks (mention / delegation) wake the agent instantly via the " + "same gateway inject path as webhook_dispatch, tagged " + 'meta.source="linear" with the agent_session_id, and the agent ' + "responds with structured AgentActivity (thought/message/complete/" + "error) via the linear_agent_activity MCP tool. Builds the " + "session-lifecycle layer on top of the plain webhook_sources:[linear] " + "+ webhook_dispatch support (#2272). The OAuth app token is stored in " + "the vault and referenced here as vault:linear/<agent>/token; run " + "`switchroom linear-agent setup <agent>` to provision it. Off by " + "default \u2014 opt in per agent. Cascades from " + "defaults.channels.telegram.linear_agent."),
     chat_id: exports_external.string().regex(/^-\d+$/, 'supergroup chat_id must be a negative integer as a string (e.g. "-1001234567890")').optional().describe("Per-agent supergroup ID \u2014 overrides fleet `telegram.forum_chat_id`. " + "When set, requires `default_topic_id`. Negative integer as string. " + "Forbidden when `dm_only: true`. See docs/rfcs/supergroup-mode.md."),
     default_topic_id: exports_external.number().int().positive().optional().describe("Forum topic ID this agent's automated outbounds default to when " + "no more-specific alias resolves. Defaults to General (topic 1) when " + "`chat_id` is set and this is omitted \u2014 set it only to pin a different " + "fallback topic. " + "Telegram's General topic is `id=1` at MTProto but sends omit the " + "field \u2014 the outbound wrapper strips `message_thread_id === 1` " + "on send. Forbidden when `dm_only: true`."),
     topic_aliases: exports_external.record(exports_external.string(), exports_external.number().int().positive()).optional().describe("Operator-friendly names for forum topic IDs (e.g. " + "`{ general: 1, planning: 17, cron: 23, admin: 31, alerts: 41 }`). " + "Referenced from per-cron `topic:` fields and the outbound router " + "for autonomous events (boot \u2192 alerts, hostd \u2192 admin, etc.). " + "Cascades per-key through defaults \u2192 profile \u2192 agent.")
@@ -44920,7 +44925,7 @@ function labelTag(label) {
 }
 
 // gateway/model-command.ts
-var MODEL_ALIASES = ["opus", "sonnet", "haiku", "default"];
+var MODEL_ALIASES = ["opus", "sonnet", "haiku", "fable", "default"];
 var MODEL_ARG_RE = /^[A-Za-z0-9][A-Za-z0-9._\[\]-]{0,99}$/;
 function isValidModelArg(arg) {
   return MODEL_ARG_RE.test(arg);
@@ -47026,6 +47031,53 @@ function injectWebhookInbound(agent, prompt, ctx, deps = {}) {
 `)).catch((err) => log(`webhook-dispatch: agent='${agent}' inject failed: ${String(err)}
 `));
 }
+function parseLinearAgentSession(payload) {
+  const type = String(payload.type ?? "").toLowerCase();
+  if (type !== "agentsessionevent")
+    return null;
+  const action = String(payload.action ?? "").toLowerCase();
+  const session = payload.agentSession ?? payload.agent_session ?? {};
+  const sessionId = String(session.id ?? payload.agentSessionId ?? payload.agent_session_id ?? "");
+  if (!sessionId)
+    return null;
+  const explicitTrigger = String(session.trigger ?? payload.trigger ?? "").toLowerCase();
+  const comment = session.comment;
+  const trigger = explicitTrigger === "mention" || explicitTrigger === "delegation" ? explicitTrigger : comment ? "mention" : "delegation";
+  const promptContext = typeof payload.promptContext === "string" ? payload.promptContext : typeof session.promptContext === "string" ? session.promptContext : undefined;
+  const issue = session.issue ?? {};
+  const issueId = String(issue.identifier ?? "");
+  const issueTitle = String(issue.title ?? "");
+  const commentBody = typeof comment?.body === "string" ? comment.body : "";
+  const summaryParts = [];
+  summaryParts.push(trigger === "mention" ? `You were @mentioned in Linear` : `An issue was delegated to you in Linear`);
+  if (issueId || issueTitle) {
+    summaryParts.push(`Issue ${issueId}${issueTitle ? `: ${issueTitle}` : ""}`.trim());
+  }
+  if (commentBody)
+    summaryParts.push(commentBody);
+  const summary = summaryParts.join(`
+`);
+  return { sessionId, trigger, action, promptContext, summary };
+}
+function buildLinearInbound(session, ctx, now) {
+  const content = session.promptContext && session.promptContext.trim().length > 0 ? session.promptContext : session.summary;
+  return {
+    type: "inbound",
+    chatId: ctx.chatId,
+    ...ctx.threadId !== undefined ? { threadId: ctx.threadId } : {},
+    messageId: now,
+    user: "linear",
+    userId: 0,
+    ts: now,
+    text: content,
+    meta: {
+      source: "linear",
+      agent_session_id: session.sessionId,
+      linear_trigger: session.trigger,
+      linear_event: `agent_session.${session.action || "event"}`
+    }
+  };
+}
 function evaluateDispatch(args, deps = {}) {
   const log = deps.log ?? ((s) => process.stderr.write(s));
   const now = (deps.now ?? Date.now)();
@@ -47137,6 +47189,38 @@ function recordWebhookEvent(rec, deps = {}) {
   }
   log(`webhook-gateway: agent='${agent}' source='${rec.source}' event='${rec.event_type}' recorded ts=${now}
 `);
+  if (rec.source === "linear") {
+    try {
+      const session = parseLinearAgentSession(rec.payload);
+      if (session) {
+        const config = (deps.loadConfig ?? loadConfig)();
+        const rawAgent = config.agents?.[agent];
+        const linearAgent = rawAgent ? resolveAgentConfig(config.defaults, config.profiles, rawAgent).channels?.telegram?.linear_agent : undefined;
+        if (!linearAgent?.enabled) {
+          log(`linear-agent: agent='${agent}' session='${session.sessionId}' ignored \u2014 linear_agent not enabled
+`);
+        } else {
+          const target = resolveChannelTarget(config, agent);
+          if (!target) {
+            log(`linear-agent: agent='${agent}' session='${session.sessionId}' skipped \u2014 no chat target (forum_chat_id / chat_id unset)
+`);
+          } else {
+            const inbound = buildLinearInbound(session, {
+              chatId: target.chatId,
+              ...target.threadId !== undefined ? { threadId: target.threadId } : {}
+            }, now);
+            const ok = deps.inject ? deps.inject(agent, inbound) : false;
+            log(`linear-agent: agent='${agent}' session='${session.sessionId}' trigger='${session.trigger}' ` + `${ok ? "injected" : "NOT injected (no inject sink)"}
+`);
+            return { status: "ok", ts: now, dispatched: ok ? 1 : 0 };
+          }
+        }
+      }
+    } catch (err) {
+      log(`linear-agent: agent='${agent}' session inject error (event recorded): ${err.message}
+`);
+    }
+  }
   let dispatched = 0;
   try {
     const config = (deps.loadConfig ?? loadConfig)();
@@ -53793,10 +53877,10 @@ function readTurnActiveMarkerAgeMs(stateDir, now) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.15.11";
-var COMMIT_SHA = "43331954";
-var COMMIT_DATE = "2026-06-13T03:24:01Z";
-var LATEST_PR = 2308;
+var VERSION = "0.15.12";
+var COMMIT_SHA = "18b7b6e6";
+var COMMIT_DATE = "2026-06-13T04:55:14Z";
+var LATEST_PR = 2311;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -54087,6 +54171,110 @@ async function revokeGrantViaBroker(id, opts) {
   return { kind: "error", msg: "unexpected broker response" };
 }
 
+// gateway/linear-activity.ts
+init_client2();
+var LINEAR_GRAPHQL_ENDPOINT = "https://api.linear.app/graphql";
+async function defaultResolveLinearToken(agent) {
+  const key = `linear/${agent}/token`;
+  const token = readVaultTokenFile(agent) ?? undefined;
+  const result = await getViaBrokerStructured(key, token ? { token } : {});
+  if (result.kind === "ok" && result.entry.kind === "string") {
+    return { ok: true, token: result.entry.value };
+  }
+  if (result.kind === "unreachable")
+    return { ok: false, reason: "unreachable" };
+  if (result.kind === "not_found")
+    return { ok: false, reason: "not_found" };
+  if (result.kind === "denied")
+    return { ok: false, reason: "denied" };
+  return { ok: false, reason: "unknown" };
+}
+async function emitLinearAgentActivity(args, deps = {}) {
+  const log = deps.log ?? ((s) => process.stderr.write(s));
+  const sessionId = args.agent_session_id;
+  if (!sessionId)
+    throw new Error("linear_agent_activity: agent_session_id is required");
+  const type = args.type;
+  if (!type || !["thought", "message", "complete", "error"].includes(type)) {
+    throw new Error("linear_agent_activity: type must be one of thought|message|complete|error");
+  }
+  const body = args.body;
+  if (type !== "complete" && (body == null || body === "")) {
+    throw new Error(`linear_agent_activity: body is required for type='${type}'`);
+  }
+  const agent = deps.agent ?? process.env.SWITCHROOM_AGENT_NAME ?? "-";
+  const resolveToken = deps.resolveToken ?? defaultResolveLinearToken;
+  const tokenResult = await resolveToken(agent);
+  if (!tokenResult.ok) {
+    if (tokenResult.reason === "denied" || tokenResult.reason === "not_found") {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `linear_agent_activity failed: no Linear token (vault ${tokenResult.reason}). ` + `Call vault_request_access for key 'linear/${agent}/token' (scope read), then retry.`
+          }
+        ]
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: `linear_agent_activity failed: vault broker ${tokenResult.reason} resolving 'linear/${agent}/token'.`
+        }
+      ]
+    };
+  }
+  const content = { type };
+  if (body != null && body !== "")
+    content.body = body;
+  const mutation = "mutation AgentActivityCreate($input: AgentActivityCreateInput!) { " + "agentActivityCreate(input: $input) { success agentActivity { id } } }";
+  const variables = { input: { agentSessionId: sessionId, content } };
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  let resp;
+  try {
+    resp = await fetchImpl(LINEAR_GRAPHQL_ENDPOINT, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: tokenResult.token
+      },
+      body: JSON.stringify({ query: mutation, variables })
+    });
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `linear_agent_activity failed: request error: ${err.message}` }]
+    };
+  }
+  if (!resp.ok) {
+    const txt = await resp.text().catch(() => "");
+    return {
+      content: [
+        { type: "text", text: `linear_agent_activity failed: Linear API ${resp.status}${txt ? ` \u2014 ${txt.slice(0, 200)}` : ""}` }
+      ]
+    };
+  }
+  let json;
+  try {
+    json = await resp.json();
+  } catch {
+    return { content: [{ type: "text", text: "linear_agent_activity failed: malformed Linear API response" }] };
+  }
+  if (json.errors && json.errors.length > 0) {
+    return {
+      content: [
+        { type: "text", text: `linear_agent_activity failed: ${json.errors.map((e) => e.message ?? "error").join("; ").slice(0, 300)}` }
+      ]
+    };
+  }
+  if (json.data?.agentActivityCreate?.success === false) {
+    return { content: [{ type: "text", text: "linear_agent_activity failed: Linear reported success=false" }] };
+  }
+  log(`telegram gateway: linear_agent_activity: emitted type=${type} session=${sessionId} agent=${agent}
+`);
+  return { content: [{ type: "text", text: `Linear ${type} emitted on session ${sessionId}` }] };
+}
+
 // vault-approval-posture.ts
 function resolveVaultApprovalPosture(broker) {
   if (broker?.approvalAuth === "telegram-id") {
@@ -57294,7 +57482,8 @@ var ALLOWED_TOOLS = new Set([
   "send_gif",
   "vault_request_save",
   "vault_request_access",
-  "request_secret"
+  "request_secret",
+  "linear_agent_activity"
 ]);
 async function executeToolCall(tool, args) {
   if (!ALLOWED_TOOLS.has(tool)) {
@@ -57339,6 +57528,8 @@ async function executeToolCall(tool, args) {
       return executeVaultRequestAccess(args);
     case "request_secret":
       return executeRequestSecret(args);
+    case "linear_agent_activity":
+      return executeLinearAgentActivity(args);
     default:
       throw new Error(`unknown tool: ${tool}`);
   }
@@ -57369,6 +57560,9 @@ async function executeSendChecklist(args) {
 `);
   return { content: [{ type: "text", text: `checklist sent (id: ${sent.message_id})` }] };
 }
+async function executeLinearAgentActivity(args) {
+  return emitLinearAgentActivity(args);
+}
 async function executeUpdateChecklist(args) {
   const chat_id = args.chat_id;
   if (!chat_id)

package/telegram-plugin/dist/server.js

@@ -24631,6 +24631,29 @@ var init_bridge = __esm(async () => {
         },
         required: ["chat_id", "key"]
       }
+    },
+    {
+      name: "linear_agent_activity",
+      description: 'Emit a structured Linear AgentActivity against an agent session (#2298). Use this ONLY inside a turn that was woken by a Linear agent session (the inbound carries meta.source="linear" and meta.agent_session_id) \u2014 pass that agent_session_id back here. Linear renders activities as status chips + a timeline on the issue, so the human sees acknowledge \u2192 work \u2192 result. Emit a `thought` within ~10s of being woken so the session does not look dead, then `message`(s) as you make progress, and finally exactly one terminal `complete` (work done) or `error` (you could not proceed). body is required for thought/message/error and optional for complete. Resolves the agent\'s Linear app token from the vault; on VAULT-BROKER-DENIED it returns an error instructing you to vault_request_access for `linear/<agent>/token`.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          agent_session_id: {
+            type: "string",
+            description: "The Linear AgentSession id \u2014 copy it verbatim from the woken turn's meta.agent_session_id."
+          },
+          type: {
+            type: "string",
+            enum: ["thought", "message", "complete", "error"],
+            description: "Activity kind. thought = visible reasoning ack (emit within ~10s); message = progress update; complete = terminal success; error = terminal failure."
+          },
+          body: {
+            type: "string",
+            description: "Activity text (Markdown). Required for thought/message/error; optional for complete (a closing summary)."
+          }
+        },
+        required: ["agent_session_id", "type"]
+      }
     }
   ];
   mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_SCHEMAS }));

package/telegram-plugin/gateway/gateway.ts

@@ -467,6 +467,7 @@ import {
   listGrantsViaBroker,
   revokeGrantViaBroker,
 } from '../../src/vault/broker/client.js'
+import { emitLinearAgentActivity } from './linear-activity.js'
 import {
   approvalRequest,
   approvalConsume,
@@ -6718,6 +6719,7 @@ const ALLOWED_TOOLS = new Set([
   'vault_request_save',
   'vault_request_access',
   'request_secret',
+  'linear_agent_activity',
 ])
 
 async function executeToolCall(tool: string, args: Record<string, unknown>): Promise<unknown> {
@@ -6763,6 +6765,8 @@ async function executeToolCall(tool: string, args: Record<string, unknown>): Pro
       return executeVaultRequestAccess(args)
     case 'request_secret':
       return executeRequestSecret(args)
+    case 'linear_agent_activity':
+      return executeLinearAgentActivity(args)
     default:
       throw new Error(`unknown tool: ${tool}`)
   }
@@ -6794,6 +6798,10 @@ async function executeSendChecklist(args: Record<string, unknown>): Promise<{ co
   return { content: [{ type: 'text', text: `checklist sent (id: ${sent.message_id})` }] }
 }
 
+async function executeLinearAgentActivity(args: Record<string, unknown>): Promise<{ content: Array<{ type: string; text: string }> }> {
+  return emitLinearAgentActivity(args)
+}
+
 async function executeUpdateChecklist(args: Record<string, unknown>): Promise<{ content: Array<{ type: string; text: string }> }> {
   const chat_id = args.chat_id as string
   if (!chat_id) throw new Error('update_checklist: chat_id is required')

package/telegram-plugin/gateway/linear-activity.ts

@@ -0,0 +1,160 @@
+/**
+ * Linear AgentActivity emission (#2298).
+ *
+ * The `linear_agent_activity` MCP tool lets an agent that was woken by a
+ * Linear agent session respond with structured activities (thought /
+ * message / complete / error) that Linear renders as status chips + a
+ * timeline on the issue. This module owns the pure logic — token
+ * resolution + the `agentActivityCreate` GraphQL POST — behind injectable
+ * deps so it is testable without a vault broker or the network. The
+ * gateway wires it into `executeToolCall`.
+ *
+ * The agent's Linear app token is resolved from the vault under
+ * `linear/<agent>/token` via the broker (never an inline literal, never an
+ * env file). On a vault denial the tool returns actionable text telling the
+ * agent to `vault_request_access` for that key rather than failing opaquely.
+ */
+
+import {
+  getViaBrokerStructured,
+  readVaultTokenFile,
+} from '../../src/vault/broker/client.js'
+
+export const LINEAR_GRAPHQL_ENDPOINT = 'https://api.linear.app/graphql'
+
+export type LinearTokenResult =
+  | { ok: true; token: string }
+  | { ok: false; reason: 'denied' | 'unreachable' | 'not_found' | 'unknown' }
+
+export interface LinearActivityDeps {
+  /** Resolve the Linear app token for `agent` from the vault. */
+  resolveToken?: (agent: string) => Promise<LinearTokenResult>
+  /** Injectable fetch (tests). */
+  fetchImpl?: typeof fetch
+  /** Agent slug (defaults to SWITCHROOM_AGENT_NAME). */
+  agent?: string
+  /** Log sink — stderr in production. */
+  log?: (line: string) => void
+}
+
+export type ToolTextResult = { content: Array<{ type: string; text: string }> }
+
+/** Default token resolver: vault broker get on `linear/<agent>/token`. */
+export async function defaultResolveLinearToken(agent: string): Promise<LinearTokenResult> {
+  const key = `linear/${agent}/token`
+  const token = readVaultTokenFile(agent) ?? undefined
+  const result = await getViaBrokerStructured(key, token ? { token } : {})
+  if (result.kind === 'ok' && result.entry.kind === 'string') {
+    return { ok: true, token: result.entry.value }
+  }
+  if (result.kind === 'unreachable') return { ok: false, reason: 'unreachable' }
+  if (result.kind === 'not_found') return { ok: false, reason: 'not_found' }
+  if (result.kind === 'denied') return { ok: false, reason: 'denied' }
+  return { ok: false, reason: 'unknown' }
+}
+
+/**
+ * Emit a Linear AgentActivity. Validates args, resolves the token, POSTs
+ * the `agentActivityCreate` mutation, and returns an MCP text result. Never
+ * throws on a vault/network failure — returns actionable error text so the
+ * agent can recover (e.g. via vault_request_access).
+ */
+export async function emitLinearAgentActivity(
+  args: Record<string, unknown>,
+  deps: LinearActivityDeps = {},
+): Promise<ToolTextResult> {
+  const log = deps.log ?? ((s) => process.stderr.write(s))
+
+  const sessionId = args.agent_session_id as string | undefined
+  if (!sessionId) throw new Error('linear_agent_activity: agent_session_id is required')
+  const type = args.type as string | undefined
+  if (!type || !['thought', 'message', 'complete', 'error'].includes(type)) {
+    throw new Error('linear_agent_activity: type must be one of thought|message|complete|error')
+  }
+  const body = args.body as string | undefined
+  if (type !== 'complete' && (body == null || body === '')) {
+    throw new Error(`linear_agent_activity: body is required for type='${type}'`)
+  }
+
+  const agent = deps.agent ?? process.env.SWITCHROOM_AGENT_NAME ?? '-'
+  const resolveToken = deps.resolveToken ?? defaultResolveLinearToken
+  const tokenResult = await resolveToken(agent)
+  if (!tokenResult.ok) {
+    if (tokenResult.reason === 'denied' || tokenResult.reason === 'not_found') {
+      return {
+        content: [
+          {
+            type: 'text',
+            text:
+              `linear_agent_activity failed: no Linear token (vault ${tokenResult.reason}). ` +
+              `Call vault_request_access for key 'linear/${agent}/token' (scope read), then retry.`,
+          },
+        ],
+      }
+    }
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `linear_agent_activity failed: vault broker ${tokenResult.reason} resolving 'linear/${agent}/token'.`,
+        },
+      ],
+    }
+  }
+
+  // AgentActivity content discriminated by type. thought/message/error carry
+  // a body; complete is terminal with an optional summary body.
+  const content: Record<string, unknown> = { type }
+  if (body != null && body !== '') content.body = body
+
+  const mutation =
+    'mutation AgentActivityCreate($input: AgentActivityCreateInput!) { ' +
+    'agentActivityCreate(input: $input) { success agentActivity { id } } }'
+  const variables = { input: { agentSessionId: sessionId, content } }
+
+  const fetchImpl = deps.fetchImpl ?? fetch
+  let resp: Response
+  try {
+    resp = await fetchImpl(LINEAR_GRAPHQL_ENDPOINT, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: tokenResult.token,
+      },
+      body: JSON.stringify({ query: mutation, variables }),
+    })
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `linear_agent_activity failed: request error: ${(err as Error).message}` }],
+    }
+  }
+
+  if (!resp.ok) {
+    const txt = await resp.text().catch(() => '')
+    return {
+      content: [
+        { type: 'text', text: `linear_agent_activity failed: Linear API ${resp.status}${txt ? ` — ${txt.slice(0, 200)}` : ''}` },
+      ],
+    }
+  }
+
+  let json: { data?: { agentActivityCreate?: { success?: boolean } }; errors?: Array<{ message?: string }> }
+  try {
+    json = (await resp.json()) as typeof json
+  } catch {
+    return { content: [{ type: 'text', text: 'linear_agent_activity failed: malformed Linear API response' }] }
+  }
+  if (json.errors && json.errors.length > 0) {
+    return {
+      content: [
+        { type: 'text', text: `linear_agent_activity failed: ${json.errors.map((e) => e.message ?? 'error').join('; ').slice(0, 300)}` },
+      ],
+    }
+  }
+  if (json.data?.agentActivityCreate?.success === false) {
+    return { content: [{ type: 'text', text: 'linear_agent_activity failed: Linear reported success=false' }] }
+  }
+
+  log(`telegram gateway: linear_agent_activity: emitted type=${type} session=${sessionId} agent=${agent}\n`)
+  return { content: [{ type: 'text', text: `Linear ${type} emitted on session ${sessionId}` }] }
+}