switchroom 0.16.22 → 0.16.24

package/telegram-plugin/gateway/inject-handler.test.ts

@@ -41,8 +41,10 @@ function makeDeps(overrides: Partial<InjectDeps> = {}): {
     },
     getAgentName: () => 'gymbro',
     getArgs: () => '/cost',
-    escapeHtml: (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'),
-    preBlock: (s) => `<pre>${s}</pre>`,
+    // #2669: production now passes the markdown escaper + fenced-block helper
+    // (matches gateway.ts's escapeHtmlForTg / preBlock).
+    escapeHtml: (s) => s.replace(/([\\`*_~=\[\]|])/g, '\\$1'),
+    preBlock: (s) => '```\n' + s + '\n```',
     ...overrides,
   }
   return { deps, replies }
@@ -112,15 +114,15 @@ describe('handleInjectCommand — outcome=ok', () => {
     expect(replies).toHaveLength(1)
     expect(replies[0].opts?.accent).toBe('done')
     expect(replies[0].text).toContain('✅')
-    expect(replies[0].text).toContain('<code>/cost</code>')
-    expect(replies[0].text).toContain('<pre>Total cost: $0.42</pre>')
+    expect(replies[0].text).toContain('`/cost`')
+    expect(replies[0].text).toContain('```\nTotal cost: $0.42\n```')
   })
 
-  it('appends <i>truncated</i> when output truncated', async () => {
+  it('appends _truncated_ when output truncated', async () => {
     const inject = vi.fn().mockResolvedValue(okResult('/cost', 'a lot of text', true))
     const { deps, replies } = makeDeps({ getArgs: () => '/cost', inject })
     await handleInjectCommand(fakeCtx(), deps)
-    expect(replies[0].text).toContain('<i>truncated</i>')
+    expect(replies[0].text).toContain('_truncated_')
     expect(replies[0].opts?.accent).toBe('done')
   })
 
@@ -138,9 +140,9 @@ describe('handleInjectCommand — outcome=ok_no_output', () => {
     const { deps, replies } = makeDeps({ getArgs: () => '/compact', inject })
     await handleInjectCommand(fakeCtx(), deps)
     expect(replies[0].opts?.accent).toBe('done')
-    expect(replies[0].text).toContain('<code>/compact</code>')
+    expect(replies[0].text).toContain('`/compact`')
     expect(replies[0].text).toContain('compaction runs silently')
-    expect(replies[0].text).not.toContain('<pre>')
+    expect(replies[0].text).not.toContain('```')
   })
 
   it('warns with accent=issue when expectsOutput=true and capture empty (/cost)', async () => {
@@ -157,10 +159,10 @@ describe('handleInjectCommand — outcome=ok_no_output', () => {
     const { deps, replies } = makeDeps({ getArgs: () => '/clear', inject })
     await handleInjectCommand(fakeCtx(), deps)
     expect(replies[0].opts?.accent).toBe('done')
-    expect(replies[0].text).toContain('<code>/clear</code>')
+    expect(replies[0].text).toContain('`/clear`')
     expect(replies[0].text).toContain('context cleared')
     expect(replies[0].text).not.toContain('empty capture')
-    expect(replies[0].text).not.toContain('<pre>')
+    expect(replies[0].text).not.toContain('```')
   })
 })
 
@@ -186,7 +188,7 @@ describe('handleInjectCommand — outcome=failed', () => {
     const { deps, replies } = makeDeps({ getArgs: () => '/login', inject })
     await handleInjectCommand(fakeCtx(), deps)
     expect(replies[0].opts?.accent).toBe('issue')
-    expect(replies[0].text).toContain('<code>/login</code>')
+    expect(replies[0].text).toContain('`/login`')
     expect(replies[0].text).toContain('blocked: would mutate auth state')
   })
 
@@ -201,7 +203,7 @@ describe('handleInjectCommand — outcome=failed', () => {
     expect(replies[0].text).toContain('experimental.legacy_pty')
   })
 
-  it('tmux_failed: surfaces escaped error message', async () => {
+  it('tmux_failed: surfaces the error message (< > literal in markdown, #2669)', async () => {
     const inject = vi
       .fn()
       .mockResolvedValue(failedResult('/cost', 'tmux_failed', 'connection <refused>'))
@@ -209,7 +211,7 @@ describe('handleInjectCommand — outcome=failed', () => {
     await handleInjectCommand(fakeCtx(), deps)
     expect(replies[0].opts?.accent).toBe('issue')
     expect(replies[0].text).toContain('tmux send-keys failed')
-    expect(replies[0].text).toContain('connection &lt;refused&gt;')
+    expect(replies[0].text).toContain('connection <refused>')
   })
 
   it('thrown InjectError from inject() is normalized to outcome=failed', async () => {

package/telegram-plugin/gateway/inject-handler.ts

@@ -57,13 +57,13 @@ function shapeReply(
   slashCommand: string,
   deps: Pick<InjectDeps, 'escapeHtml' | 'preBlock' | 'formatOutput'>,
 ): { body: string; accent: InjectAccent } {
-  const verbHtml = `<code>${deps.escapeHtml(result.command || slashCommand)}</code>`
+  const verbHtml = `\`${deps.escapeHtml(result.command || slashCommand)}\``
 
   if (result.outcome === 'ok') {
     const formatted = deps.formatOutput ? deps.formatOutput(result.output) : result.output
     let body = `${verbHtml}\n${deps.preBlock(formatted)}`
     if (result.diagnostic === 'truncated_output' || result.truncated) {
-      body += '\n<i>truncated</i>'
+      body += '\n_truncated_'
     }
     return { body, accent: 'done' }
   }
@@ -105,13 +105,13 @@ function shapeReply(
   }
   if (code === 'session_missing') {
     return {
-      body: 'tmux session not found — agent must be running under the tmux supervisor (the default). Remove <code>experimental.legacy_pty: true</code> if set.',
+      body: 'tmux session not found — agent must be running under the tmux supervisor (the default). Remove \`experimental.legacy_pty: true\` if set.',
       accent: 'issue',
     }
   }
   if (code === 'invalid') {
     return {
-      body: 'usage: <code>/inject /&lt;command&gt;</code>',
+      body: 'usage: \`/inject /<command>\`',
       accent: 'issue',
     }
   }
@@ -140,7 +140,7 @@ export async function handleInjectCommand(ctx: Context, deps: InjectDeps): Promi
     const allow = [...INJECT_COMMANDS.keys()].sort().join(', ')
     await deps.reply(
       ctx,
-      `Usage: <code>/inject &lt;slashCommand&gt;</code>\nAllowed: <code>${deps.escapeHtml(allow)}</code>`,
+      `Usage: \`/inject <slashCommand>\`\nAllowed: \`${deps.escapeHtml(allow)}\``,
       { html: true },
     )
     return

package/telegram-plugin/gateway/ipc-protocol.ts

@@ -462,6 +462,37 @@ export interface SendOutboundMessage {
   parseMode?: "html" | "text";
 }
 
+/**
+ * #2670 (one-tap self-improvement) — post a skill-improvement proposal as
+ * a one-tap Approve/Dismiss card. Sent by the weekly skill-synthesis flow
+ * (`switchroom self-improve propose-skill`) after it drafts a candidate
+ * personal skill. The gateway PERSISTS the proposal (full draft bundle) to
+ * the self-improve proposal store and posts the card to the agent's own
+ * chat. The Approve tap is handled gateway-side: it injects a
+ * `skill_proposal_apply` turn so the agent writes the stored draft through
+ * the personal-skill pipeline (secret-scan runs; no self-escalation).
+ *
+ * Trust model identical to send_outbound / inject_inbound: per-agent
+ * socket, agentName validated, chat fenced to the agent's own chat.
+ */
+export interface PostSkillProposalMessage {
+  type: "post_skill_proposal";
+  agentName: string;
+  /** Agent's own chat id (fenced server-side). */
+  chatId: string;
+  threadId?: number;
+  /** Target personal-skill slug (without the `personal-` prefix). */
+  skillSlug: string;
+  /** True = new skill; false = edit an existing personal skill. */
+  isNew: boolean;
+  /** One-line lesson the skill captures. */
+  lesson: string;
+  /** Short evidence line (e.g. "seen across 3 sessions"). */
+  evidence: string;
+  /** Full drafted skill bundle (SKILL.md + optional files). */
+  draft: Record<string, string>;
+}
+
 export type ClientToGateway =
   | RegisterMessage
   | ToolCallMessage
@@ -478,4 +509,5 @@ export type ClientToGateway =
   | RequestConfigApprovalMessage
   | RequestConfigFinalizeMessage
   | QuotaWallDetectedMessage
-  | SendOutboundMessage;
+  | SendOutboundMessage
+  | PostSkillProposalMessage;

package/telegram-plugin/gateway/ipc-server.ts

@@ -6,6 +6,7 @@ import type {
   InjectInboundMessage,
   SendOutboundMessage,
   QuotaWallDetectedMessage,
+  PostSkillProposalMessage,
   OperatorEventForward,
   PermissionRequestForward,
   PtyPartialForward,
@@ -63,6 +64,13 @@ export interface IpcServerOptions {
    * don't run failover simply ignore it.
    */
   onQuotaWallDetected?: (client: IpcClient, msg: QuotaWallDetectedMessage) => void;
+  /**
+   * #2670 one-tap self-improvement — persist a skill-improvement proposal
+   * and post its Approve/Dismiss card. Handler persists the draft bundle to
+   * the self-improve proposal store and posts the card to the agent's own
+   * chat. Optional; gateways that don't surface proposals ignore it.
+   */
+  onPostSkillProposal?: (client: IpcClient, msg: PostSkillProposalMessage) => void;
   /**
    * RFC E §4.2 Cut 2 — Drive-write PreToolUse hook asks the gateway
    * to register a kernel approval request + post a diff-preview
@@ -271,6 +279,22 @@ export function validateClientMessage(msg: unknown): msg is ClientToGateway {
       if (m.parseMode !== undefined && m.parseMode !== "html" && m.parseMode !== "text") return false;
       return true;
     }
+    case "post_skill_proposal": {
+      // #2670 one-tap self-improvement — validate the wire shape; the
+      // gateway handler fences chatId to the agent's own chat.
+      if (typeof m.agentName !== "string"
+        || !AGENT_NAME_RE.test(m.agentName as string)) return false;
+      if (typeof m.chatId !== "string" || (m.chatId as string).length === 0) return false;
+      if (typeof m.skillSlug !== "string" || (m.skillSlug as string).length === 0) return false;
+      if (typeof m.isNew !== "boolean") return false;
+      if (typeof m.lesson !== "string" || (m.lesson as string).length === 0) return false;
+      if (typeof m.evidence !== "string") return false;
+      if (typeof m.draft !== "object" || m.draft === null || Array.isArray(m.draft)) return false;
+      if (typeof (m.draft as Record<string, unknown>)["SKILL.md"] !== "string") return false;
+      if (m.threadId !== undefined
+        && (typeof m.threadId !== "number" || !Number.isInteger(m.threadId as number))) return false;
+      return true;
+    }
     case "quota_wall_detected": {
       // wedge-watchdog detected the /rate-limit-options weekly-quota menu.
       if (typeof m.agentName !== "string"
@@ -372,6 +396,7 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
     onInjectInbound,
     onSendOutbound,
     onQuotaWallDetected,
+    onPostSkillProposal,
     onRequestDriveApproval,
     onRequestMs365Approval,
     onRequestConfigApproval,
@@ -483,6 +508,9 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
       case "send_outbound":
         if (onSendOutbound) onSendOutbound(client, msg as SendOutboundMessage);
         break;
+      case "post_skill_proposal":
+        if (onPostSkillProposal) onPostSkillProposal(client, msg as PostSkillProposalMessage);
+        break;
       case "quota_wall_detected":
         if (onQuotaWallDetected) onQuotaWallDetected(client, msg as QuotaWallDetectedMessage);
         break;

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

@@ -27,30 +27,32 @@ export const LINEAR_GRAPHQL_ENDPOINT = 'https://api.linear.app/graphql'
 /** The two operator-action reasons a Linear 401 can't self-heal. */
 export type LinearAuthDeadReason = 'no_bundle' | 'revoked'
 
-/** Minimal HTML-escape (Telegram parse_mode: 'HTML'). Kept local so the
- *  message builder is self-contained + unit-testable without reaching into a
- *  gateway-only escaper (the bug that shipped the first cut of this alert). */
-function escapeHtmlMin(s: string): string {
-  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+/** Minimal GFM-markdown escape (#2669). Kept local so the message builder is
+ *  self-contained + unit-testable without reaching into a gateway-only
+ *  escaper (the bug that shipped the first cut of this alert). */
+function escapeMarkdownMin(s: string): string {
+  return s.replace(/([\\`*_~=\[\]|])/g, '\\$1')
 }
 
 /**
- * Build the operator-facing Telegram alert (HTML) for an un-healable Linear
- * auth failure. Pure + self-escaping so it can be unit-tested directly. The
- * gateway's `notifyLinearAuthDead` only handles dedup + transport.
+ * Build the operator-facing Telegram alert (GFM markdown) for an un-healable
+ * Linear auth failure. Pure + self-escaping so it can be unit-tested directly.
+ * The gateway's `notifyLinearAuthDead` only handles dedup + transport.
  */
 export function buildLinearAuthDeadMessage(agent: string, reason: LinearAuthDeadReason): string {
-  const a = escapeHtmlMin(agent)
+  // Inside `code` spans the agent slug is literal (no escaping); in prose it
+  // is markdown-escaped.
+  const aEsc = escapeMarkdownMin(agent)
   const why =
     reason === 'no_bundle'
-      ? `no refresh credentials are stored (<code>linear/${a}/oauth</code> is missing), so its daily-expiring token can't renew`
+      ? `no refresh credentials are stored (\`linear/${agent}/oauth\` is missing), so its daily-expiring token can't renew`
       : `its Linear refresh token was revoked`
   return (
-    `🔑 <b>Linear auth needs you</b>\n` +
-    `<b>${a}</b> can't reach Linear — ${why}. ` +
+    `🔑 **Linear auth needs you**\n` +
+    `**${aEsc}** can't reach Linear — ${why}. ` +
     `Its access token will keep failing until you re-authorize.\n\n` +
-    `Re-auth (actor=app) then run <code>switchroom linear-agent setup --agent ${a} ` +
-    `--token … --refresh-token … --client-id … --client-secret …</code> on the host, ` +
+    `Re-auth (actor=app) then run \`switchroom linear-agent setup --agent ${agent} ` +
+    `--token … --refresh-token … --client-id … --client-secret …\` on the host, ` +
     `or ask me to walk you through it.`
   )
 }

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

@@ -130,7 +130,7 @@ export async function runLinearAgentSetup(
   if (action === 'authorize_url') {
     const url = buildLinearAuthorizeUrl({ clientId, redirectUri })
     return text(
-      `Open this URL in a browser to authorize <b>${agent}</b> as a Linear app actor (actor=app):\n\n${url}\n\n` +
+      `Open this URL in a browser to authorize **${agent}** as a Linear app actor (actor=app):\n\n${url}\n\n` +
         `After you approve, Linear redirects to ${redirectUri}?code=… (it may show a blank/error page — that's fine). ` +
         `Copy the code value from the URL bar, then run linear_agent_setup with action "complete", the same client_id + redirect_uri, ` +
         `your client_secret, and that code.`,

package/telegram-plugin/gateway/model-command.ts

@@ -141,17 +141,17 @@ export interface ModelCommandReply {
 }
 
 const PERSIST_NOTE =
-  '<i>Session-only — lasts until restart. To persist, set <code>model:</code> in switchroom.yaml and restart.</i>'
+  '_Session-only — lasts until restart. To persist, set \`model:\` in switchroom.yaml and restart._'
 
 function helpText(deps: ModelCommandDeps, reason?: string): ModelCommandReply {
-  const srAliasExamples = Object.keys(SR_MODEL_ALIASES).map(a => `<code>${a}</code>`).join(' · ')
+  const srAliasExamples = Object.keys(SR_MODEL_ALIASES).map(a => `\`${a}\``).join(' · ')
   const lines: string[] = []
   if (reason) lines.push(`⚠️ ${deps.escapeHtml(reason)}`)
   lines.push(
-    '<b>/model</b> — show or switch the Claude model',
-    '<code>/model</code> — show the configured model',
-    `<code>/model &lt;name&gt;</code> — switch the live session (${MODEL_ALIASES.map(a => `<code>${a}</code>`).join(' · ')} or a full model id)`,
-    `<i>OpenRouter shortcuts:</i> ${srAliasExamples}`,
+    '**/model** — show or switch the Claude model',
+    '\`/model\` — show the configured model',
+    `\`/model <name>\` — switch the live session (${MODEL_ALIASES.map(a => `\`${a}\``).join(' · ')} or a full model id)`,
+    `_OpenRouter shortcuts:_ ${srAliasExamples}`,
     PERSIST_NOTE,
   )
   return { text: lines.join('\n'), html: true }
@@ -166,14 +166,14 @@ export async function handleModelCommand(
   if (parsed.kind === 'show') {
     const configured = deps.getConfiguredModel()
     const shown = configured && configured.length > 0 ? configured : 'default'
-    const srAliasExamples = Object.keys(SR_MODEL_ALIASES).map(a => `<code>/model ${a}</code>`).join(' · ')
+    const srAliasExamples = Object.keys(SR_MODEL_ALIASES).map(a => `\`/model ${a}\``).join(' · ')
     return {
       text: [
-        `<b>Model — ${deps.escapeHtml(deps.getAgentName())}</b>`,
-        `Configured: <code>${deps.escapeHtml(shown)}</code>`,
-        `Switch the live session: ${MODEL_ALIASES.map(a => `<code>/model ${a}</code>`).join(' · ')}`,
+        `**Model — ${deps.escapeHtml(deps.getAgentName())}**`,
+        `Configured: \`${deps.escapeHtml(shown)}\``,
+        `Switch the live session: ${MODEL_ALIASES.map(a => `\`/model ${a}\``).join(' · ')}`,
         `OpenRouter shortcuts: ${srAliasExamples}`,
-        'or <code>/model &lt;full-model-id&gt;</code>',
+        'or \`/model <full-model-id>\`',
         PERSIST_NOTE,
       ].join('\n'),
       html: true,
@@ -207,14 +207,14 @@ export async function handleModelCommand(
     }
     return {
       text: [
-        `Switching from <code>${deps.escapeHtml(currentSession)}</code> back to Claude — restarting session cleanly. Claude will be ready in ~30s.`,
+        `Switching from \`${deps.escapeHtml(currentSession)}\` back to Claude — restarting session cleanly. Claude will be ready in ~30s.`,
         PERSIST_NOTE,
       ].join('\n'),
       html: true,
     }
   }
 
-  const verbHtml = `<code>/model ${deps.escapeHtml(model)}</code>`
+  const verbHtml = `\`/model ${deps.escapeHtml(model)}\``
   let result: InjectResult
   try {
     result = await deps.inject(deps.getAgentName(), `/model ${model}`)
@@ -231,7 +231,7 @@ export async function handleModelCommand(
       text: [
         `${verbHtml}`,
         deps.preBlock(result.output),
-        ...(result.truncated ? ['<i>truncated</i>'] : []),
+        ...(result.truncated ? ['_truncated_'] : []),
         PERSIST_NOTE,
       ].join('\n'),
       html: true,
@@ -241,7 +241,7 @@ export async function handleModelCommand(
   if (result.outcome === 'ok_no_output') {
     return {
       text: [
-        `${verbHtml} — sent, but no response captured. The agent may be mid-turn; check <code>/inject /status</code> to confirm the active model.`,
+        `${verbHtml} — sent, but no response captured. The agent may be mid-turn; check \`/inject /status\` to confirm the active model.`,
         PERSIST_NOTE,
       ].join('\n'),
       html: true,
@@ -252,7 +252,7 @@ export async function handleModelCommand(
   if (result.errorCode === 'session_missing') {
     return {
       text:
-        '❌ tmux session not found — the agent must be running under the tmux supervisor (the default). Remove <code>experimental.legacy_pty: true</code> if set.',
+        '❌ tmux session not found — the agent must be running under the tmux supervisor (the default). Remove \`experimental.legacy_pty: true\` if set.',
       html: true,
     }
   }
@@ -447,7 +447,7 @@ export async function buildModelMenu(
     // with the discovery failure surfaced.
     const v1 = await handleModelCommand({ kind: 'show' }, deps)
     return {
-      text: [`<i>(picker unavailable: ${deps.escapeHtml(discovered.reason)})</i>`, v1.text].join('\n'),
+      text: [`_(picker unavailable: ${deps.escapeHtml(discovered.reason)})_`, v1.text].join('\n'),
       html: true,
     }
   }
@@ -462,18 +462,18 @@ export async function buildModelMenu(
   const { claude: claudeOptions } = classifyDiscoveredOptions(discovered.options)
   const srOptions: ModelPickerOption[] = srNames.map((name, i) => ({ index: i, label: name, detail: '', current: false }))
   const current = claudeOptions.find((o) => o.current)
-  const lines: string[] = [`<b>Model — ${deps.escapeHtml(deps.getAgentName())}</b>`]
+  const lines: string[] = [`**Model — ${deps.escapeHtml(deps.getAgentName())}**`]
   if (discovered.dismissFailed) {
-    lines.push('⚠️ <i>The picker may still be open on the agent pane — check it before switching.</i>')
+    lines.push('⚠️ _The picker may still be open on the agent pane — check it before switching._')
   }
   if (current) {
     const detail = current.detail ? ` · ${deps.escapeHtml(current.detail)}` : ''
-    lines.push(`Default (new sessions): <b>${deps.escapeHtml(current.label)}</b>${detail}`)
+    lines.push(`Default (new sessions): **${deps.escapeHtml(current.label)}**${detail}`)
   } else {
-    lines.push('Default (new sessions): <i>unknown (no ✔ row in picker)</i>')
+    lines.push('Default (new sessions): _unknown (no ✔ row in picker)_')
   }
   if (quota) lines.push(`Quota: ${deps.escapeHtml(quota)}`)
-  lines.push('', 'Tap a model to switch the <b>live session</b>:')
+  lines.push('', 'Tap a model to switch the **live session**:')
   if (srOptions.length > 0) {
     lines.push('Claude models use your Max/Pro subscription. 🌐 models are billed separately via OpenRouter.')
   }
@@ -548,7 +548,7 @@ export async function handleModelMenuCallback(
       const msg = err instanceof Error ? err.message : String(err)
       return {
         answer: 'Switch failed',
-        reply: await menuWithBanner(deps, `❌ Switch to <b>${deps.escapeHtml(srName)}</b> failed: ${deps.escapeHtml(msg)}`),
+        reply: await menuWithBanner(deps, `❌ Switch to **${deps.escapeHtml(srName)}** failed: ${deps.escapeHtml(msg)}`),
       }
     }
     if (srResult.outcome === 'ok') {
@@ -572,7 +572,7 @@ export async function handleModelMenuCallback(
       answer: 'Switch failed',
       reply: await menuWithBanner(
         deps,
-        `❌ Switch to <b>${deps.escapeHtml(srFriendlyLabel(srName))}</b> failed — agent may be mid-turn`,
+        `❌ Switch to **${deps.escapeHtml(srFriendlyLabel(srName))}** failed — agent may be mid-turn`,
       ),
     }
   }
@@ -628,7 +628,7 @@ export async function handleModelMenuCallback(
       answer: 'Switch failed — see the menu',
       reply: await menuWithBanner(
         deps,
-        `❌ Switch to <b>${deps.escapeHtml(target.label)}</b> failed: ${deps.escapeHtml(result.reason)}`,
+        `❌ Switch to **${deps.escapeHtml(target.label)}** failed: ${deps.escapeHtml(result.reason)}`,
       ),
     }
   }

package/telegram-plugin/gateway/oversize-card-body.ts

@@ -1,13 +1,12 @@
 /**
  * Shared "render-and-fit" helper for approval cards that wrap
- * user-supplied content in HTML framing. (#1762 / #1767)
+ * user-supplied content in markdown framing. (#1762 / #1767 / #2669)
  *
- * Telegram's `sendMessage` caps the body at 4096 chars and we render
- * with `parse_mode=HTML`. Worst-case escape inflates raw content up
- * to 5x (`&` → `&`), so a naive raw-input cap is unsafe — the
- * post-escape body can blow past the limit and `sendMessage` then
- * returns a generic 400 that surfaces upstream as a silent
- * `E_DENIED`.
+ * Telegram's rich-message body caps at 32768 chars. Content shipped
+ * inside a fenced code block is literal (no escape inflation), but the
+ * surrounding framing still counts toward the cap — so a naive raw-input
+ * cap can blow past the limit and the send then returns a generic 400
+ * that surfaces upstream as a silent `E_DENIED`.
  *
  * This helper binary-searches the largest prefix of the RAW content
  * whose rendered body still fits under `cap`, snaps to the last

package/telegram-plugin/gateway/skill-proposal-card.ts

@@ -0,0 +1,167 @@
+/**
+ * One-tap skill-improvement proposal card (#2670, "one-tap
+ * self-improvement").
+ *
+ * The weekly skill-synthesis cron drafts a proposed personal skill and
+ * persists it (full draft bundle) in the self-improve proposal store
+ * (`src/self-improve/skill-proposals.ts`). This module renders that
+ * proposal as a Telegram Approve / Dismiss card and builds the synthetic
+ * inbound the gateway injects when the operator taps Approve — instructing
+ * the live agent to APPLY the stored draft through the existing
+ * `skill_init_personal` / `skill_edit_personal` write pipeline (so the
+ * merged `scanBundleForSecrets` gate runs; the agent never self-applies —
+ * the operator tap is the authorization, satisfying `no-self-escalation`).
+ *
+ * Pure builders, kept out of gateway.ts so the card text + callback shape
+ * + inbound shape are pinned by tests independent of the bot plumbing.
+ *
+ * callback_data shape (must fit Telegram's 64-byte limit):
+ *   skprop:approve:<id>
+ *   skprop:deny:<id>
+ * where <id> is the proposal's UUID from the store.
+ */
+
+import type { InboundMessage } from './ipc-protocol.js'
+
+export const SKILL_PROPOSAL_CALLBACK_PREFIX = 'skprop:'
+
+/** Narrow shape of a stored proposal the card/inbound builders need.
+ *  Mirrors SkillProposal in src/self-improve/skill-proposals.ts without
+ *  importing across the tsconfig boundary. */
+export interface SkillProposalView {
+  id: string
+  skill_slug: string
+  is_new: boolean
+  lesson: string
+  evidence: string
+  /** SKILL.md body, for the optional "show full draft" / step preview. */
+  skill_md?: string
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+/** A short bullet preview of the drafted procedure (first few non-empty,
+ *  non-frontmatter lines of SKILL.md), capped for the card. */
+export function previewSteps(skillMd: string | undefined, maxLines = 5): string[] {
+  if (!skillMd) return []
+  // Drop YAML frontmatter block if present.
+  let body = skillMd
+  if (body.startsWith('---')) {
+    const end = body.indexOf('\n---', 3)
+    if (end >= 0) body = body.slice(body.indexOf('\n', end + 1) + 1)
+  }
+  const out: string[] = []
+  for (const raw of body.split('\n')) {
+    const line = raw.trim()
+    if (!line || line.startsWith('#')) continue
+    out.push(line.replace(/^[-*\d.)\s]+/, '').slice(0, 120))
+    if (out.length >= maxLines) break
+  }
+  return out
+}
+
+/** Render the proposal card text (HTML parse mode). */
+export function renderSkillProposalCard(p: SkillProposalView): string {
+  const verb = p.is_new ? 'New personal skill' : 'Update to personal skill'
+  const lines: string[] = []
+  lines.push(`🧩 <b>Skill improvement proposed</b>`)
+  lines.push('')
+  lines.push(`<b>${escapeHtml(verb)}:</b> <code>${escapeHtml(p.skill_slug)}</code>`)
+  lines.push(`<b>Lesson:</b> ${escapeHtml(p.lesson)}`)
+  if (p.evidence) lines.push(`<i>${escapeHtml(p.evidence)}</i>`)
+  const steps = previewSteps(p.skill_md)
+  if (steps.length > 0) {
+    lines.push('')
+    lines.push('<b>Draft procedure:</b>')
+    for (const s of steps) lines.push(`• ${escapeHtml(s)}`)
+  }
+  lines.push('')
+  lines.push(
+    '<i>Tap Add to apply it (runs through the secret-scan write pipeline). ' +
+      'Tap Dismiss and it won’t be proposed again.</i>',
+  )
+  return lines.join('\n')
+}
+
+/** Inline keyboard for the proposal card. */
+export function skillProposalKeyboard(id: string): {
+  inline_keyboard: Array<Array<{ text: string; callback_data: string }>>
+} {
+  return {
+    inline_keyboard: [
+      [
+        { text: '✅ Add skill', callback_data: `${SKILL_PROPOSAL_CALLBACK_PREFIX}approve:${id}` },
+        { text: '🚫 Dismiss', callback_data: `${SKILL_PROPOSAL_CALLBACK_PREFIX}deny:${id}` },
+      ],
+    ],
+  }
+}
+
+/** Parse a `skprop:` callback into { action, id }, or null if not ours. */
+export function parseSkillProposalCallback(
+  data: string,
+): { action: 'approve' | 'deny'; id: string } | null {
+  if (!data.startsWith(SKILL_PROPOSAL_CALLBACK_PREFIX)) return null
+  const rest = data.slice(SKILL_PROPOSAL_CALLBACK_PREFIX.length)
+  const idx = rest.indexOf(':')
+  if (idx < 0) return null
+  const action = rest.slice(0, idx)
+  const id = rest.slice(idx + 1)
+  if ((action !== 'approve' && action !== 'deny') || id.length === 0) return null
+  return { action, id }
+}
+
+export interface SkillProposalInboundContext {
+  agent: string
+  chat_id: string
+  threadId?: number
+}
+
+/**
+ * Build the synthetic inbound injected when the operator taps Approve.
+ * It instructs the live agent to apply the stored draft via the personal-
+ * skill write pipeline — the agent never self-applies; this tap is the
+ * authorization. `meta.source = "skill_proposal_apply"` so the bridge
+ * renders it as `<channel source="skill_proposal_apply">`.
+ */
+export function buildSkillProposalApplyInbound(opts: {
+  ctx: SkillProposalInboundContext
+  proposalId: string
+  skillSlug: string
+  isNew: boolean
+  operatorId: string
+  nowMs?: number
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  const tool = opts.isNew ? 'skill_init_personal' : 'skill_edit_personal'
+  return {
+    type: 'inbound',
+    chatId: opts.ctx.chat_id,
+    ...(opts.ctx.threadId != null ? { threadId: opts.ctx.threadId } : {}),
+    messageId: ts,
+    user: 'skill-synthesis',
+    userId: 0,
+    ts,
+    text:
+      `✅ Operator approved your proposed skill \`${opts.skillSlug}\` ` +
+      `(proposal ${opts.proposalId}). Apply it now: read the stored draft ` +
+      `from the self-improve proposal store and call \`${tool}\` with that ` +
+      `exact draft bundle. Do NOT re-draft or add anything from this ` +
+      `conversation — write the stored bundle verbatim so the secret-scan ` +
+      `write pipeline validates it. Confirm to the operator when it lands.`,
+    meta: {
+      source: 'skill_proposal_apply',
+      agent: opts.ctx.agent,
+      ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
+      proposal_id: opts.proposalId,
+      skill_slug: opts.skillSlug,
+      is_new: String(opts.isNew),
+      operator_id: opts.operatorId,
+    },
+  }
+}