@0xmaxma/claude-gateway 1.8.14 → 2.0.0

package/mcp/tools/receiver-spool.ts

@@ -0,0 +1,56 @@
+import { mediaGroupKey, mergeMediaGroup, type ChannelInput } from './telegram/media-group';
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readdirSync, openSync, closeSync, writeFileSync, fsyncSync, renameSync, readFileSync, unlinkSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Receiver-local handoff journal. Persist before returning to the platform
+ * client; only remove after the gateway confirms its SQLite admission. */
+export class ReceiverSpool {
+  private active = false;
+  private readonly timer: ReturnType<typeof setInterval>;
+  constructor(private readonly directory: string, private readonly callback: string, private readonly request: typeof fetch = fetch, private readonly mediaGroupWaitMs = 2000) {
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    this.timer = setInterval(() => { void this.flush(); }, 1000); this.timer.unref();
+    void this.flush();
+  }
+  enqueue(input: unknown): void {
+    const group=mediaGroupKey(input as ChannelInput);
+    if(group){
+      let prior:ChannelInput|undefined;
+      try{prior=JSON.parse(readFileSync(join(this.directory,`${group}.json`),'utf8'));}catch{}
+      input=mergeMediaGroup(prior,input as ChannelInput);
+    }
+    const payload = JSON.stringify(input);
+    if (Buffer.byteLength(payload) > 131072) throw new Error('Ingress payload too large');
+    if (readdirSync(this.directory).filter(file => file.endsWith('.json')).length >= 1000) throw new Error('Ingress spool full');
+    const key = group ?? createHash('sha256').update(payload).digest('hex');
+    const temporary = join(this.directory, `${key}.${randomUUID()}.tmp`);
+    const descriptor = openSync(temporary, 'wx', 0o600);
+    try { writeFileSync(descriptor, payload); fsyncSync(descriptor); } finally { closeSync(descriptor); }
+    renameSync(temporary, join(this.directory, `${key}.json`));
+    this.syncDirectory();
+    void this.flush();
+  }
+  private syncDirectory(): void {
+    const descriptor = openSync(this.directory, 'r');
+    try { fsyncSync(descriptor); } finally { closeSync(descriptor); }
+  }
+  async flush(): Promise<void> {
+    if (this.active) return;
+    this.active = true;
+    try {
+      const files = readdirSync(this.directory).filter(file => /^[a-f0-9]{64}\.json$/.test(file)).map(file => ({ file, created: statSync(join(this.directory, file)).mtimeMs })).sort((a, b) => a.created - b.created);
+      for (const { file } of files.slice(0, 100)) {
+        const location = join(this.directory, file);
+        const payload=readFileSync(location,'utf8');
+        const input=JSON.parse(payload) as ChannelInput;
+        if(mediaGroupKey(input)&&Date.now()-statSync(location).mtimeMs<this.mediaGroupWaitMs)continue;
+        const response = await this.request(this.callback, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: payload, signal: AbortSignal.timeout(10000) });
+        if (!response.ok) break;
+        if(readFileSync(location,'utf8')===payload){unlinkSync(location); this.syncDirectory();}
+      }
+    } catch { /* persisted message is retried on next tick or process restart */ }
+    finally { this.active = false; }
+  }
+  close(): void { clearInterval(this.timer); }
+}

package/mcp/tools/share-file/module.ts

@@ -28,7 +28,15 @@ export class ShareFileModule implements ToolModule {
   }
 
   getTools(): McpToolDefinition[] {
-    return shareFileToolDefs;
+    if (process.env.GATEWAY_ORCHESTRATION_ROLE !== 'worker') return shareFileToolDefs;
+    return shareFileToolDefs.map(tool => ({
+      ...tool,
+      description: tool.description + ' In a task, use the original absolute file path in the active task workspace, a supplied input attachment or this session’s media directory. The gateway stages it automatically; do not copy it to the agent-wide media root. Describe this as creating a link (Thai: สร้างลิงก์).',
+      inputSchema: { ...shareFileInputSchema, properties: { ...shareFileInputSchema.properties,
+        path: { type: 'string', description: 'Original absolute file path in the active task workspace or session media, or artifact:<id>.' },
+        paths: { type: 'array', items: { type: 'string' }, description: 'Up to 5 authorized absolute file paths or artifact refs.' },
+      } },
+    }));
   }
 
   async handleTool(name: string, args: Record<string, unknown>): Promise<McpToolResult> {

package/mcp/tools/shared/share-client.ts

@@ -71,6 +71,7 @@ export class ShareClientError extends Error {
  * is absent the private mint endpoint is not mounted and calls fail closed.
  */
 export function shareBridgeEnabled(): boolean {
+  if (process.env.GATEWAY_ORCHESTRATION_ROLE === 'worker' && process.env.GATEWAY_ORCHESTRATION_MEDIA === 'true' && process.env.GATEWAY_ORCHESTRATION_TICKET_FILE) return true;
   return (
     !!process.env.GATEWAY_API_URL &&
     !!process.env.GATEWAY_API_KEY &&
@@ -88,6 +89,24 @@ async function callGateway(
   pathname: string,
   body?: Record<string, unknown>,
 ): Promise<{ status: number; json: Record<string, unknown> }> {
+  if (process.env.GATEWAY_ORCHESTRATION_ROLE === 'worker' && process.env.GATEWAY_ORCHESTRATION_TICKET_FILE) {
+    const { readFile } = await import('node:fs/promises');
+    const ticket = JSON.parse(await readFile(process.env.GATEWAY_ORCHESTRATION_TICKET_FILE, 'utf8'));
+    const response = await fetch(ticket.url, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${ticket.token}` },
+      body: JSON.stringify({ tool: 'task_share_call', action_id: crypto.randomUUID(), args: { method, pathname, body } }), signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    if (!response.ok) {
+      const failure = await response.json().catch(() => ({})) as Record<string, unknown> | null;
+      // The bridge uses {error: CODE}; retain that cause instead of treating
+      // path validation, stale attempts and unavailable configuration alike.
+      const code = typeof failure?.error === 'string' && /^[A-Z][A-Z0-9_]{0,79}$/.test(failure.error)
+        ? failure.error : 'share_scope_denied';
+      const error = code === 'ARTIFACT_PATH_DENIED'
+        ? 'File is outside this task scope. Use the original file’s absolute path in the active task workspace, a supplied input attachment, or this session’s media directory. Do not copy it to the agent-wide media root. The gateway stages authorized files automatically.'
+        : code === 'share_scope_denied' ? 'Scoped share request denied' : code;
+      return { status: response.status, json: { error, code } };
+    }
+    return await response.json() as { status: number; json: Record<string, unknown> };
+  }
   const res = await fetch(`${apiBase()}${pathname}`, {
     method,
     headers: {

package/mcp/tools/tasks/module.ts

@@ -0,0 +1,35 @@
+// MCP sources are published, src/ is not. Share the compiled schema so an
+// installed package has the same inventory as a development checkout.
+import { WORKFLOW_SCHEMA } from '../../../dist/orchestration/workflow.js';
+import type { McpToolDefinition, McpToolResult } from '../../types';
+
+const schema = (properties: Record<string, unknown>, required: string[]) => ({ type: 'object', properties, required, additionalProperties: false });
+const text = { type: 'string' };
+export const AGENT_TASK_TOOLS: McpToolDefinition[] = [
+  { name: 'capabilities_list', description: 'Discover all capabilities this agent can offer: installed/shared/native skills, gateway MCP tools and enabled connector/plugin MCP tools, including tools executed only by workers. Read metadata only; never executes a tool or grants permissions. Use query to find relevant tools before assigning work. Follow next_offset until null when the user asks for the complete list, passing catalog_version from the first page. On CAPABILITY_CATALOG_CHANGED restart from offset 0. Report unavailable discovery honestly; do not confuse your own restricted callable tools with the capabilities of the agent as a whole.', inputSchema: schema({query:text,catalog_version:text,offset:{type:'integer',minimum:0}},[]) },
+  { name: 'conversation_intake', description: 'Prepare executable work, incomplete materials, or an amendment to an existing task. Do not call this for greetings, introductions, casual conversation or questions you can answer directly; answer those normally once. When semantic intake is enabled, acknowledge before work mutations. Incomplete material is inspected now; the gateway asks the supplied clarification after the configured silence interval, not on every item.',
+    inputSchema: schema({mode:{type:'string',enum:['ready','wait','update']},acknowledgement:{type:'string',description:'A brief contextual message addressed directly to the user about the work you will do. Immediately displayed and spoken aloud. Never include private classification, reasoning, or instructions to yourself.'},preparation:text,clarification:text,task_id:text},['mode']) },
+  { name: 'task_spawn', description: 'Durably queue a task for an independent worker. Returns after commit without waiting for worker startup or completion.',
+    inputSchema: schema({ title: text, instructions: text, target_profile: text, spoken_acknowledgement: { type: 'string', description: 'Required for live voice: a short natural response in the user language explaining the specific work you are about to do. Describe the specific user request as your own task, in the voice of your existing persona; do not announce handing it to a worker or use a generic acknowledgement. Speak as the person doing the work; avoid Thai delegation phrases such as สั่งเช็คแล้ว, สั่งไปแล้ว or ส่งให้ตรวจแล้ว. Describe queued work as accepted/to do next, and only say it is running when that state is confirmed. Do not claim completion. The gateway manages playback and channel text-before-voice ordering.' }, skill_name: { type: 'string', description: 'Exact installed gateway or discovered Claude Code runtime skill name for skill-worker. Native skills are invoked directly by the CLI; shared/workspace skills are supplied with their resources. Never supply a file path.' }, skill_args: { type: 'string', description: 'Arguments for the installed skill; required with skill_name.' }, continue_task_id: { type: 'string', description: 'Prior task ID in this conversation for related follow-up work. Reuses its worker session when compatible; waits for success by default. Queue every authorized dependent step now, using each returned task ID for the next step. Omit for independent work.' }, continuation_policy: { type: 'string', enum: ['after_success', 'after_terminal'], description: 'With continue_task_id: after_success (default) starts only after the predecessor succeeds; otherwise fails without executing. Use after_terminal only for explicitly authorized recovery/inspection that must run after failure or cancellation.' }, context_refs: { type: 'array', items: text, description: 'Only orchestration input IDs, authorized attachment refs or task artifact IDs. Put project filenames in instructions instead.' } }, ['title', 'instructions', 'target_profile']) },
+  { name: 'task_status', description: 'Read the task index in this conversation without waiting. Pass task_id to retrieve the complete stored result and evidence before discussing an earlier task. An index entry is not a partial worker report.', inputSchema: schema({ task_id: text }, []) },
+  { name: 'task_cancel', description: 'Request cancellation, including needs_reconciliation cleanup. cancel_requested is not proof of termination. Existing files are retained. Set replaced_by_task_id only for a known replacement task, never infer from similar titles.', inputSchema: schema({ task_id: text, replaced_by_task_id: text }, ['task_id']) },
+  { name: 'task_update', description: 'Accept a revised task instruction. applied_revision changes only when the worker accepts it.', inputSchema: schema({ task_id: text, expected_revision: { type: 'integer', minimum: 1 }, instruction: text, mode: { type: 'string', enum: ['when_ready', 'interrupt_and_resume'] } }, ['task_id', 'expected_revision', 'instruction', 'mode']) },
+  { name: 'task_answer', description: 'Answer the matching pending question on a task.', inputSchema: schema({ task_id: text, question_id: text, answer: text }, ['task_id', 'question_id', 'answer']) },
+];
+export const WORKER_REPORT_TOOLS: McpToolDefinition[] = [
+  { name: 'task_memory_append', description: 'Append an explicitly requested memory note for a channel task. API tasks cannot write memory. Files are restricted to MEMORY.md, USER.md, or memory/<name>.md. Retains existing content and deduplicates retries.', inputSchema: schema({ note: text, path: text }, ['note']) },
+  { name: 'task_stage_file', description: 'Stage a finished image or document for the user. The orchestration attaches it to the next completed agent response after this task succeeds, using the original destination. This tool does not send to a channel. Call once per output file. For an image returned by an MCP tool (such as a remote browser screenshot), omit path to use the latest captured image in this attempt, or pass source_tool_call_id to select its tool call. The gateway saves the actual image bytes; never invent a screenshot filename. For an existing local file supply path.', inputSchema: schema({ path: text, source_tool_call_id: text, caption: text }, []) },
+  { name: 'task_report_progress', description: 'Report factual progress internally. At phase changes include a checkpoint with phase, evidenceVersion, checks, findings and nextAction. This does not send a user message.', inputSchema: schema({ text, checkpoint: WORKFLOW_SCHEMA }, ['text']) },
+  { name: 'task_request_input', description: 'Ask the user for information required by your task, then end this turn immediately.', inputSchema: schema({ question: text }, ['question']) },
+];
+
+export async function callTaskBridge(tool: string, args: Record<string, unknown>, requestId: string, signal: AbortSignal): Promise<McpToolResult> {
+  // Rotated by the gateway at each decision/attempt boundary. A loaded token is
+  // immutable for this request; late requests cannot borrow the next decision.
+  const { readFile } = await import('node:fs/promises');
+  const scope = JSON.parse(await readFile(process.env.GATEWAY_ORCHESTRATION_TICKET_FILE!, 'utf8')) as { url: string; token: string };
+  const response = await fetch(scope.url, { method: 'POST', signal, headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${scope.token}` },
+    body: JSON.stringify({ tool, args, action_id: requestId }) });
+  const body = await response.text();
+  return { content: [{ type: 'text', text: body }], ...(response.ok ? {} : { isError: true }) };
+}

package/mcp/tools/telegram/media-group.ts

@@ -0,0 +1,21 @@
+import { createHash } from 'node:crypto';
+export type ChannelInput = {content:string;meta:Record<string,string>};
+export function mediaGroupKey(input: ChannelInput): string | undefined {
+ const m=input?.meta;
+ return m?.media_group_id ? createHash('sha256').update(JSON.stringify([m.chat_id,m.user_id,m.message_thread_id??'',m.media_group_id])).digest('hex') : undefined;
+}
+/** Telegram albums arrive as separate updates. Keep the native group intact. */
+export function mergeMediaGroup(prior:ChannelInput|undefined,input:ChannelInput):ChannelInput {
+ const ids:string[]=prior?JSON.parse(prior.meta.message_ids_json):[];
+ if(ids.includes(input.meta.message_id))return prior!;
+ if(ids.length>=10)throw Error('Telegram media group exceeds 10 items');
+ const parts:Array<{id:string;caption:string;ref?:string;path?:string;name?:string}> = prior?JSON.parse(prior.meta.media_group_parts_json):[];
+ parts.push({id:input.meta.message_id,caption:input.meta.media_caption??'',ref:input.meta.attachment_file_id,path:input.meta.image_path,name:input.meta.attachment_name});
+ parts.sort((a,b)=>Number(a.id)-Number(b.id));
+ const meta:Record<string,string>={...(prior?.meta??input.meta),media_group_id:input.meta.media_group_id,message_id:parts[0]!.id,
+  message_ids_json:JSON.stringify(parts.map(p=>p.id)),media_group_parts_json:JSON.stringify(parts),
+  attachments_json:JSON.stringify(parts.map(({ref,path,name})=>({ref,path,name})))};
+ // Album files must not turn a mixed album into a single-file voice-note turn.
+ delete meta.attachment_file_id;delete meta.image_path;delete meta.attachment_kind;
+ return {content:parts.map(p=>p.caption).filter(Boolean).join('\n\n')||'[Media album attached]',meta};
+}

package/mcp/tools/telegram/receiver-server.ts

@@ -25,6 +25,13 @@ import { z } from 'zod'
 import { Bot, GrammyError, InlineKeyboard, InputFile, type Context } from 'grammy'
 import type { ReactionTypeEmoji } from 'grammy/types'
 import { randomBytes } from 'crypto'
+import { confirmSelection, voiceModeConfirmation } from './selection-confirmation'
+import { LiveTaskBrowser, type TaskBrowserMessage } from './task-browser'
+import { ReceiverSpool } from '../receiver-spool'
+const orchestrationSpool = process.env.GATEWAY_ORCHESTRATION_INGRESS_DIR && process.env.CLAUDE_CHANNEL_CALLBACK
+  ? new ReceiverSpool(process.env.GATEWAY_ORCHESTRATION_INGRESS_DIR, process.env.CLAUDE_CHANNEL_CALLBACK, fetch, Math.max(250,Math.min(10000,Number(process.env.GATEWAY_MEDIA_GROUP_WAIT_MS)||2000))) : undefined
+const ORCHESTRATION_ENABLED = process.env.GATEWAY_ORCHESTRATION_ENABLED === 'true' || Boolean(orchestrationSpool)
+const INTERACTIVE_CLI_ENABLED = process.env.GATEWAY_INTERACTIVE_CLI_ENABLED === 'true' && !ORCHESTRATION_ENABLED
 import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, statSync, renameSync, realpathSync, chmodSync, existsSync } from 'fs'
 import { homedir } from 'os'
 import { join, extname, sep } from 'path'
@@ -35,6 +42,7 @@ import { extractRepliedAttachment, safeName } from './reply-attachment'
 // so a src/ import crashes this bun-run receiver on installed packages (the bug
 // that silenced every bot on systemd installs). Enforced by
 // tests/unit/mcp-no-src-imports.test.ts.
+import { formatTaskDetail, type TaskDetail } from './task-detail'
 import { formatTurnIncident, type TurnIncident } from '../../../dist/agent/turn-trace.js'
 import { createIncidentStore } from '../../../dist/agent/incident-store.js'
 import type { RecoveryOutcome } from '../../../dist/agent/incident.js'
@@ -214,6 +222,7 @@ const typingManager = createWorkingStateManager(
       )
     }
   },
+  ORCHESTRATION_ENABLED ? 'orchestration' : 'legacy',
 )
 
 // Stages whose recovery must run in the runner process (live session control):
@@ -863,17 +872,18 @@ const RECEIVER_MODE = process.env.TELEGRAM_RECEIVER_MODE === 'true'
 import { parseMenuFileContent } from './menu-parser'
 
 const BOT_COMMANDS = [
+  ...(ORCHESTRATION_ENABLED ? [{ command: 'tasks', description: 'View pending tasks in this chat' }, { command: 'voice', description: 'Turn automatic voice replies on or off' }, { command: 'voices', description: 'Choose the agent voice' }] : []),
   { command: 'session', description: 'Show current session info' },
   { command: 'sessions', description: 'Manage conversation sessions' },
   { command: 'new', description: 'Create a new session' },
   { command: 'rename', description: 'Rename current session' },
   { command: 'clear', description: 'Clear current session history' },
   { command: 'compact', description: 'Summarize and compress session history' },
-  { command: 'stop', description: 'Interrupt the agent and stop current work' },
+  { command: 'stop', description: ORCHESTRATION_ENABLED ? 'Stop the agent reply and choose a task to cancel' : 'Interrupt the agent and stop current work' },
   { command: 'restart', description: 'Graceful restart session' },
   { command: 'model', description: 'Show current AI model' },
   { command: 'models', description: 'Switch AI model' },
-  { command: 'cli', description: 'Open the live terminal viewer' },
+  ...(INTERACTIVE_CLI_ENABLED ? [{ command: 'cli', description: 'Open the live terminal viewer' }] : []),
   { command: 'start', description: 'Welcome and setup guide' },
   { command: 'status', description: 'Check your pairing status' },
   { command: 'help', description: 'What this bot can do' },
@@ -1023,7 +1033,7 @@ async function handleInbound(
   // Download photo from replied-to message if present
   const replyMsg = ctx.message?.reply_to_message
   let repliedImagePath: string | undefined
-  if (replyMsg?.photo) {
+  if (replyMsg?.photo && !orchestrationSpool) {
     try {
       const largest = replyMsg.photo[replyMsg.photo.length - 1]!
       const file = await bot.api.getFile(largest.file_id)
@@ -1054,7 +1064,9 @@ async function handleInbound(
     content: text,
     meta: {
       chat_id,
+      ...(ctx.message?.media_group_id ? {media_group_id:ctx.message.media_group_id,media_caption:ctx.message.caption??''} : {}),
       ...(msgId != null ? { message_id: String(msgId) } : {}),
+      ...(ctx.message?.message_thread_id != null ? { message_thread_id: String(ctx.message.message_thread_id) } : {}),
       user: from.username ?? String(from.id),
       user_id: String(from.id),
       // Human-readable name for the chat picker / history (first_name is always
@@ -1072,8 +1084,9 @@ async function handleInbound(
       ...(replyMsg ? {
         replied_message_id: String(replyMsg.message_id),
         replied_user: replyMsg.from?.username ?? String(replyMsg.from?.id ?? ''),
-        ...(replyMsg.text ? { replied_text: replyMsg.text } : {}),
+        ...((replyMsg.text || replyMsg.caption) ? { replied_text: replyMsg.text || replyMsg.caption } : {}),
         ...(repliedImagePath ? { replied_image_path: repliedImagePath } : {}),
+        ...(orchestrationSpool && replyMsg.photo ? {replied_attachment_file_id:replyMsg.photo[replyMsg.photo.length-1]!.file_id} : {}),
         ...(repliedAttachment ? {
           replied_attachment_kind: repliedAttachment.kind,
           replied_attachment_file_id: repliedAttachment.file_id,
@@ -1103,15 +1116,16 @@ async function handleInbound(
   // turns in --print --channels mode).
   const callbackUrl = process.env.CLAUDE_CHANNEL_CALLBACK
   if (callbackUrl) {
-    fetch(callbackUrl, {
+    if (orchestrationSpool) orchestrationSpool.enqueue(channelParams)
+    else fetch(callbackUrl, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(channelParams),
     }).catch(err => {
       process.stderr.write(`telegram channel: callback POST failed: ${err}\n`)
     })
-    // Start typing indicator loop — only in receiver mode with a real AgentRunner
-    if (RECEIVER_MODE) {
+    // Legacy turn watchdog only. Orchestration owns typing through durable task/decision state.
+    if (RECEIVER_MODE && !ORCHESTRATION_ENABLED) {
       typingManager.start(chat_id)
     }
   }
@@ -1157,12 +1171,13 @@ bot.command('help', async ctx => {
     `/rename <name> — rename current session\n` +
     `/clear — clear current session history\n` +
     `/compact — summarise and compress session history\n` +
-    `/stop — interrupt the running turn\n` +
+    (ORCHESTRATION_ENABLED ? `/stop — stop the reply and choose a task to cancel\n` : `/stop — interrupt the running turn\n`) +
     `/restart — graceful restart session\n\n` +
     `*Agent*\n` +
     `/model — show current AI model\n` +
     `/models — switch AI model\n` +
-    `/cli — open the live terminal viewer\n\n` +
+    (ORCHESTRATION_ENABLED ? `/tasks — view pending tasks in this chat\n/voice — turn automatic voice replies on/off (default off)\n/voices — choose the agent voice\n` : '') +
+    (INTERACTIVE_CLI_ENABLED ? `/cli — open the live terminal viewer\n\n` : '\n') +
     `*Account*\n` +
     `/start — pairing instructions\n` +
     `/status — check your pairing state`,
@@ -1295,6 +1310,7 @@ bot.command('models', async ctx => {
 // this bot's token), so nothing secret rides in the URL. Private chat + allowlist
 // only, matching every other command.
 bot.command('cli', async ctx => {
+  if (!INTERACTIVE_CLI_ENABLED) { await ctx.reply('Terminal viewer requires interactive mode (headless: false).'); return }
   if (ctx.chat?.type !== 'private') return
   const access = loadAccess()
   if (!access.allowFrom.includes(String(ctx.from!.id))) return
@@ -1360,6 +1376,144 @@ bot.command('restart', async ctx => {
   )
 })
 
+type VoicePicker = {menuId:string;provider:string;page:number;pages:number;gender?:string;groups:string[];selected:string;voices:Array<{name:string;gender?:string;index:number;selected:boolean}>}
+async function voicePickerRequest(chatId:string,userId:string,payload:Record<string,unknown>={}) {
+  if(!CALLBACK_URL_BASE)throw new Error('not_configured')
+  const response=await fetch(CALLBACK_URL_BASE+'/command',{method:'POST',headers:{'Content-Type':'application/json'},signal:AbortSignal.timeout(20000),body:JSON.stringify({command:'telegram_voices',chat_id:chatId,payload:{...payload,user_id:userId}})})
+  const result=await response.json() as VoicePicker & {success?:boolean;name?:string}
+  if(!response.ok||!result.success)throw new Error('unavailable')
+  return result
+}
+function voicePickerMenu(menu:VoicePicker) {
+  const keyboard=new InlineKeyboard()
+  const labels:Record<string,string>={male:'👨 Male',female:'👩 Female',neutral:'Neutral',unspecified:'Unspecified'}
+  if(!menu.gender){
+    for(const group of menu.groups)keyboard.text(labels[group],`voicegroup:${menu.menuId}:${group}`).row()
+  }else{
+    for(const v of menu.voices)keyboard.text(`${v.selected?'✅ ':''}${v.name.slice(0,60)}`,`voicepick:${menu.menuId}:${v.index}`).row()
+    if(menu.page>0)keyboard.text('Previous',`voicepage:${menu.menuId}:${menu.gender}:${menu.page-1}`)
+    if(menu.page+1<menu.pages)keyboard.text('Next',`voicepage:${menu.menuId}:${menu.gender}:${menu.page+1}`)
+    keyboard.row().text('Back',`voicegroup:${menu.menuId}:back`).row()
+  }
+  keyboard.text('Dismiss',`voicedismiss:${menu.menuId}`)
+  return {text:`Agent voice · ${menu.provider}\nSelected: ${menu.selected}\n${menu.gender?`${labels[menu.gender]} — choose a voice (${menu.page+1}/${menu.pages}):`:'Choose a voice category:'}`,reply_markup:keyboard}
+}
+bot.command('voices',async ctx=>{
+  if(ctx.chat?.type!=='private'||!isCallbackAuthorized(ctx))return
+  if(!ORCHESTRATION_ENABLED){await ctx.reply('Voice controls require orchestration mode.');return}
+  try{const menu=voicePickerMenu(await voicePickerRequest(String(ctx.chat.id),String(ctx.from!.id)));await ctx.reply(menu.text,{reply_markup:menu.reply_markup})}
+  catch{await ctx.reply('Voice list unavailable. Check the TTS provider configuration and try /voices again.')}
+})
+
+type TaskView = TaskDetail & {taskId:string;title:string;state:string;progress?:string;question?:string;updatedAt:number;startedAt?:number;finishedAt?:number;canStop:boolean}
+type TaskBrowser = {sessionId:string;task?:TaskView;tasks?:TaskView[];page?:number;pages?:number;total?:number}
+async function taskBrowserRequest(chatId:string,userId:string,payload:Record<string,unknown>={}) {
+  if(!CALLBACK_URL_BASE)throw Error('not_configured')
+  const response=await fetch(CALLBACK_URL_BASE+'/command',{method:'POST',headers:{'Content-Type':'application/json'},signal:AbortSignal.timeout(10000),body:JSON.stringify({command:'telegram_tasks',chat_id:chatId,payload:{...payload,user_id:userId}})})
+  const result=await response.json() as TaskBrowser & {success?:boolean}
+  if(!response.ok||!result.success)throw Error((result as {error?:string}).error==='TASK_SESSION_CHANGED'?'TASK_SESSION_CHANGED':'unavailable')
+  if(typeof result.sessionId!=='string'||!result.sessionId)throw Error('unavailable')
+  return result
+}
+function taskBrowserMenu(result:TaskBrowser) {
+  const keyboard=new InlineKeyboard()
+  const labels:Record<string,string>={queued:'⏳ Queued',starting:'⏳ Starting',running:'🔥 Running',waiting_input:'💬 Waiting for your input',interrupting:'⏸ Interrupting',cancel_requested:'⏹ Stopping',recovering:'🔄 Recovering',needs_reconciliation:'⚠️ Needs reconciliation',completed:'✅ Completed',failed:'❌ Failed',cancelled:'⏹ Cancelled'}
+  let text:string
+  if(result.task){
+    const task=result.task
+    text=formatTaskDetail(task,labels[task.state]??task.state)
+    if(task.canStop)keyboard.text(task.state==='needs_reconciliation'?'🔄 Retry cleanup':'🔴 Stop task',`taskcancel:${task.taskId}`).row()
+    keyboard.text('Back','tasklist:0').row()
+  }else{
+    text=result.total?`Tasks (${result.total}) · Page ${(result.page??0)+1}/${result.pages}\nChoose a task for details.`:'No pending tasks in this chat.'
+    for(const [i,task] of (result.tasks??[]).entries())keyboard.text(`${(result.page??0)*10+i+1}. ${task.title.replace(/\s+/g,' ').slice(0,45)} · ${labels[task.state]??task.state}`,`taskview:${task.taskId}`).row()
+    if((result.page??0)>0)keyboard.text('Previous',`tasklist:${result.page!-1}`)
+    if((result.page??0)+1<(result.pages??1))keyboard.text('Next',`tasklist:${result.page!+1}`)
+    keyboard.row()
+  }
+  keyboard.text('Dismiss','taskdismiss')
+  return {text,reply_markup:keyboard}
+}
+const TASK_BROWSER_FILE = join(STATE_DIR, 'task-browser.json')
+let restoredTaskBrowsers: TaskBrowserMessage[] = []
+try { const saved = JSON.parse(readFileSync(TASK_BROWSER_FILE, 'utf8')); if (Array.isArray(saved)) restoredTaskBrowsers = saved } catch {}
+const liveTaskBrowser = new LiveTaskBrowser({
+  read: taskBrowserRequest,
+  render: result => taskBrowserMenu(result as TaskBrowser),
+  send: async (chat, menu) => (await bot.api.sendMessage(chat, menu.text, {reply_markup: menu.reply_markup as InlineKeyboard})).message_id,
+  edit: (chat, id, menu) => bot.api.editMessageText(chat, id, menu.text, {reply_markup: menu.reply_markup as InlineKeyboard}),
+  remove: (chat, id) => bot.api.deleteMessage(chat, id),
+  close: (chat, id) => bot.api.editMessageText(chat, id, 'Task view closed.', {reply_markup: {inline_keyboard: []}}),
+  allowed: (chat, user) => ORCHESTRATION_ENABLED && chat === user && loadAccess().allowFrom.includes(user),
+  persist: entries => {
+    mkdirSync(STATE_DIR, {recursive:true,mode:0o700})
+    const temp = TASK_BROWSER_FILE + '.tmp'
+    writeFileSync(temp,JSON.stringify(entries),{mode:0o600});renameSync(temp,TASK_BROWSER_FILE)
+  },
+}, restoredTaskBrowsers)
+if (ORCHESTRATION_ENABLED) setInterval(() => { void liveTaskBrowser.tick().catch(() => {}) }, 3000).unref()
+bot.command('tasks',async ctx=>{
+  if(ctx.chat?.type!=='private'||!isCallbackAuthorized(ctx))return
+  if(!ORCHESTRATION_ENABLED){await ctx.reply('Task controls require orchestration mode.');return}
+  try{await liveTaskBrowser.open(String(ctx.chat.id),String(ctx.from!.id))}
+  catch{await ctx.reply('Could not load tasks. Please try /tasks again.')}
+})
+
+async function taskStopRequest(chatId: string, userId: string, menuId?: string, index?: number) {
+  if (!CALLBACK_URL_BASE) throw new Error('not_configured')
+  const response=await fetch(CALLBACK_URL_BASE+'/command', {
+    method:'POST',headers:{'Content-Type':'application/json'},signal:AbortSignal.timeout(10000),
+    body:JSON.stringify({command:'task_stop',chat_id:chatId,payload:{user_id:userId,menu_id:menuId,index}}),
+  })
+  const result=await response.json() as {success?:boolean;legacy?:boolean;text?:string;menuId?:string;tasks?:Array<{title:string;state:string}>}
+  if (!response.ok || !result.success) throw new Error('unavailable')
+  return result
+}
+bot.command('stop',async (ctx,next)=>{
+  if (!ORCHESTRATION_ENABLED || ctx.chat?.type!=='private') return next()
+  if (!isCallbackAuthorized(ctx)) return
+  try {
+    const result=await taskStopRequest(String(ctx.chat.id),String(ctx.from!.id))
+    if (result.legacy) return
+    const keyboard=new InlineKeyboard()
+    for (const [i,task] of (result.tasks??[]).entries()) keyboard.text(`${i+1}. ${task.title.slice(0,65)} (${task.state})`,`taskstop:${result.menuId}:${i+1}`).row()
+    if (result.tasks?.length) keyboard.text('Dismiss',`taskstop:${result.menuId}:0`)
+    await ctx.reply(result.text??'Nothing to stop.',result.tasks?.length?{reply_markup:keyboard}:{})
+  } catch { await ctx.reply('Could not load tasks. Please try /stop again.') }
+})
+
+// Voice settings are handled directly; no model call or TTS for this menu.
+type VoiceReplyMode = 'on' | 'auto' | 'off'
+async function telegramVoiceSetting(chatId: string, mode?: VoiceReplyMode): Promise<VoiceReplyMode> {
+  if (!CALLBACK_URL_BASE) throw new Error('not_configured')
+  const response = await fetch(CALLBACK_URL_BASE + '/command', {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ command: 'telegram_voice', chat_id: chatId, payload: { mode } }),
+    signal: AbortSignal.timeout(10000),
+  })
+  const result = await response.json() as { success?: boolean; enabled?: boolean; mode?: VoiceReplyMode }
+  if (!response.ok || !result.success || typeof result.enabled !== 'boolean') throw new Error('unavailable')
+  return result.mode ?? (result.enabled ? 'on' : 'off')
+}
+function voiceMenu(mode: VoiceReplyMode) {
+  const labels = {on:'🔊 Always', auto:'🎙️ Only reply voice message', off:'🔇 Off'}
+  const keyboard = new InlineKeyboard()
+  for (const value of ['on','auto','off'] as const) keyboard.text(`${mode === value ? '✅ ' : ''}${labels[value]}`, `voice:${value}`).row()
+  return {text: `Voice replies: ${labels[mode]}\nAuto replies with audio to voice messages and their task results.`, reply_markup: keyboard.text('Dismiss','voice:dismiss')}
+}
+bot.command('voice', async ctx => {
+  if (!ORCHESTRATION_ENABLED) { await ctx.reply('Voice controls require orchestration mode.'); return }
+  if (ctx.chat?.type !== 'private' || !isCallbackAuthorized(ctx)) return
+  const choice = ctx.match.trim().toLowerCase()
+  if (choice && choice !== 'on' && choice !== 'off' && choice !== 'auto') {
+    await ctx.reply('Use /voice to open the menu, or /voice on, /voice auto and /voice off.'); return
+  }
+  try {
+    const menu = voiceMenu(await telegramVoiceSetting(String(ctx.chat.id), choice ? choice as VoiceReplyMode : undefined))
+    await ctx.reply(menu.text, choice ? {} : { reply_markup: menu.reply_markup })
+  } catch { await ctx.reply('Voice settings are unavailable. Check the agent TTS configuration.') }
+})
+
 // /session — show current session info (direct command, no typing manager)
 bot.command('session', async ctx => {
   if (ctx.chat?.type !== 'private') return
@@ -1481,6 +1635,69 @@ function validModelRows(value: unknown): Array<{ id: string; label: string }> {
 bot.on('callback_query:data', async ctx => {
   const data = ctx.callbackQuery.data
 
+  const voicePicker=/^(voicepick|voicepage|voicegroup|voicedismiss):([a-f0-9-]{36})(?::(male|female|neutral|unspecified|back))?(?::(\d+))?$/.exec(data)
+  if(voicePicker){
+    if(!ORCHESTRATION_ENABLED||ctx.callbackQuery.message?.chat.type!=='private'||!isCallbackAuthorized(ctx)){await ctx.answerCallbackQuery({text:'Not available or not authorized.'}).catch(()=>{});return}
+    try{
+      const action=voicePicker[1],id=voicePicker[2],n=Number(voicePicker[4]),chatId=String(ctx.callbackQuery.message.chat.id),userId=String(ctx.from.id)
+      if(action==='voicepage'||action==='voicegroup'){
+        const menu=voicePickerMenu(await voicePickerRequest(chatId,userId,{menu_id:id,page:action==='voicepage'?n:0,gender:voicePicker[3]==='back'?undefined:voicePicker[3]}))
+        await ctx.editMessageText(menu.text,{reply_markup:menu.reply_markup}).catch(()=>{});await ctx.answerCallbackQuery().catch(()=>{})
+      }else{
+        const result=await voicePickerRequest(chatId,userId,{action:action==='voicepick'?'choose':'dismiss',menu_id:id,index:n})
+        await ctx.answerCallbackQuery({text:action==='voicepick'?`Selected: ${result.name}`.slice(0,180):'Dismissed'}).catch(()=>{})
+        if(action==='voicepick') await confirmSelection(ctx,`✅ Agent voice: ${result.name} · ${result.provider}`)
+        else await ctx.deleteMessage().catch(()=>{})
+      }
+    }catch{await ctx.answerCallbackQuery({text:'Voice list changed or unavailable. Use /voices again.'}).catch(()=>{})}
+    return
+  }
+
+  const taskBrowser=/^(taskview|taskcancel):([a-f0-9-]{36})$|^(tasklist):(\d+)$|^(taskdismiss)$/.exec(data)
+  if(taskBrowser){
+    if(!ORCHESTRATION_ENABLED||ctx.callbackQuery.message?.chat.type!=='private'||!isCallbackAuthorized(ctx)){await ctx.answerCallbackQuery({text:'Not available or not authorized.'}).catch(()=>{});return}
+    try{
+      await ctx.answerCallbackQuery().catch(()=>{})
+      const payload=data==='taskdismiss'?{action:'dismiss'}:taskBrowser[1]?{action:taskBrowser[1]==='taskcancel'?'cancel':'detail',task_id:taskBrowser[2]}:{page:Number(taskBrowser[4])}
+      await liveTaskBrowser.navigate(String(ctx.callbackQuery.message.chat.id),String(ctx.from.id),ctx.callbackQuery.message.message_id,payload)
+    }catch{await ctx.answerCallbackQuery({text:'Task unavailable. Use /tasks to refresh.'}).catch(()=>{})}
+    return
+  }
+
+  const taskStop=/^taskstop:([a-f0-9-]{36}):(\d+)$/.exec(data)
+  if (taskStop) {
+    if (!ORCHESTRATION_ENABLED) { await ctx.answerCallbackQuery({text:'Task controls require orchestration mode.'}).catch(()=>{}); return }
+    if (ctx.callbackQuery.message?.chat.type!=='private' || !isCallbackAuthorized(ctx)) {
+      await ctx.answerCallbackQuery({text:'Not authorized.'}).catch(()=>{}); return
+    }
+    try {
+      const result=await taskStopRequest(String(ctx.callbackQuery.message.chat.id),String(ctx.from.id),taskStop[1],Number(taskStop[2]))
+      await ctx.answerCallbackQuery({text:Number(taskStop[2])===0?'Dismissed':'Stop requested.'}).catch(()=>{})
+      await ctx.deleteMessage().catch(()=>{})
+      if (Number(taskStop[2])!==0) await ctx.reply(result.text??'Stop requested.')
+    } catch { await ctx.answerCallbackQuery({text:'Selection unavailable. Use /stop to refresh.'}).catch(()=>{}) }
+    return
+  }
+
+  if (data === 'voice:on' || data === 'voice:auto' || data === 'voice:off' || data === 'voice:dismiss') {
+    if (!ORCHESTRATION_ENABLED) { await ctx.answerCallbackQuery({text:'Voice controls require orchestration mode.'}).catch(()=>{}); return }
+    if (ctx.callbackQuery.message?.chat.type !== 'private' || !isCallbackAuthorized(ctx)) {
+      await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {}); return
+    }
+    if (data === 'voice:dismiss') {
+      await ctx.answerCallbackQuery({ text: 'Dismissed' }).catch(() => {})
+      await ctx.deleteMessage().catch(() => {})
+      return
+    }
+    try {
+      await telegramVoiceSetting(String(ctx.callbackQuery.message.chat.id), data.slice(6) as VoiceReplyMode)
+      const confirmation=voiceModeConfirmation(data.slice(6))
+      await ctx.answerCallbackQuery({text:confirmation}).catch(()=>{})
+      await confirmSelection(ctx,confirmation)
+    } catch { await ctx.answerCallbackQuery({ text: 'Could not update voice settings. Please try again.' }).catch(() => {}) }
+    return
+  }
+
   // Handle interactive-menu choice: choice:<N>. A tap is routed back exactly like
   // the user typing "N" — same content + meta as the text path — so the session's
   // pending-menu handler injects the selection into the PTY. Security mirrors the
@@ -1514,7 +1731,7 @@ bot.on('callback_query:data', async ctx => {
       }).catch(err => {
         process.stderr.write(`telegram channel: choice callback POST failed: ${err}\n`)
       })
-      if (RECEIVER_MODE) typingManager.start(chat_id)
+      if (RECEIVER_MODE && !ORCHESTRATION_ENABLED) typingManager.start(chat_id)
     }
     return
   }
@@ -1732,7 +1949,7 @@ bot.on('callback_query:data', async ctx => {
       await ctx.answerCallbackQuery({ text: 'Compacting...' }).catch(() => {})
       await ctx.deleteMessage().catch(() => {})
       await ctx.reply('🧠 Session compacting, please wait...\nThis may take a moment.').catch(() => {})
-      if (RECEIVER_MODE) {
+      if (RECEIVER_MODE && !ORCHESTRATION_ENABLED) {
         typingManager.start(chatId)
       }
       await fetch(CALLBACK_URL_BASE + '/command', {
@@ -1978,6 +2195,10 @@ bot.on('message:text', async ctx => {
 
 bot.on('message:photo', async ctx => {
   const caption = ctx.message.caption ?? '(photo)'
+  if(orchestrationSpool){
+    const photo=ctx.message.photo[ctx.message.photo.length-1]!;
+    await handleInbound(ctx,caption,undefined,{kind:'photo',file_id:photo.file_id,size:photo.file_size,mime:'image/jpeg'});return;
+  }
   // Defer download until after the gate approves — any user can send photos,
   // and we don't want to burn API quota or fill the inbox for dropped messages.
   await handleInbound(ctx, caption, async () => {

package/mcp/tools/telegram/selection-confirmation.ts

@@ -0,0 +1,20 @@
+/** Keep a durable confirmation in chat, matching the /models menu behavior. */
+export async function confirmSelection(ctx: {
+  editMessageText(text: string, options: {reply_markup: {inline_keyboard: never[]}}): Promise<unknown>;
+  reply(text: string): Promise<unknown>;
+  deleteMessage(): Promise<unknown>;
+}, text: string): Promise<void> {
+  try { await ctx.editMessageText(text, {reply_markup: {inline_keyboard: []}}); }
+  catch (error) {
+    if (/message is not modified/i.test(String((error as any)?.description ?? (error as any)?.message))) return;
+    // If Telegram cannot edit an old menu, retain the confirmation as a new
+    // message before removing the old controls. Never lose both.
+    await ctx.reply(text);
+    await ctx.deleteMessage().catch(() => {});
+  }
+}
+export function voiceModeConfirmation(mode: string): string {
+  const labels: Record<string,string> = {on:'Always',auto:'Only reply voice message',off:'Off'};
+  if (!(mode in labels)) throw Error('INVALID_VOICE_MODE');
+  return `✅ Voice replies: ${labels[mode]}`;
+}