@0xmaxma/claude-gateway 1.8.13 → 2.0.0

package/mcp/tools/discord/module.ts

@@ -190,6 +190,10 @@ export class DiscordModule implements ChannelModule {
     const { createDiscordClient } = await import('./client');
     this.client = await createDiscordClient(token);
     this.running = true;
+    if(process.env.CLAUDE_CHANNEL_CALLBACK){
+      const {registerCommands}=await import('./commands');
+      await registerCommands(this.client,token,process.env.GATEWAY_ORCHESTRATION_ENABLED==='true',process.env.GATEWAY_INTERACTIVE_CLI_ENABLED==='true').catch(err=>process.stderr.write(`discord: command registration failed: ${err}\n`));
+    }
   }
 
   async start(handler: InboundMessageHandler, signal: AbortSignal): Promise<void> {
@@ -296,7 +300,12 @@ export class DiscordModule implements ChannelModule {
       // button) instead of forwarding the text to the agent. Only reached after
       // gate() authorized this user, so it inherits the channel's access control.
       const cliText = (msg.content ?? '').replace(/<@!?\d+>/g, '').trim().toLowerCase();
+      if(/^\/(voice|voices|tasks|stop|help|orch)(?:\s|$)/.test(cliText)){
+        await handler({channel:'discord',accountId:this.client.user?.id??'discord',senderId:context.userId,chatId:context.channelId,chatType:isDM?'direct':'group',text:(msg.content??'').replace(/<@!?\d+>/g,'').trim(),messageId:msg.id,ts:Date.now()});
+        return;
+      }
       if (cliText === '/cli') {
+        if(process.env.GATEWAY_INTERACTIVE_CLI_ENABLED!=='true'){await msg.channel.send('The terminal viewer requires interactive mode.');return;}
         const base = cliCallbackBase();
         try {
           const res = await fetch(base + '/command', {
@@ -336,7 +345,7 @@ export class DiscordModule implements ChannelModule {
       const typingFileDir = path.join(this.stateDir, 'typing');
       try {
         fs.mkdirSync(typingFileDir, { recursive: true });
-        fs.writeFileSync(path.join(typingFileDir, channelId), '');
+        if (process.env.GATEWAY_ORCHESTRATION_ENABLED !== 'true') fs.writeFileSync(path.join(typingFileDir, channelId), '');
         await fetch(`https://discord.com/api/v10/channels/${channelId}/typing`, {
           method: 'POST',
           headers: { Authorization: `Bot ${this.getToken()!}`, 'Content-Length': '0' },
@@ -388,7 +397,14 @@ export class DiscordModule implements ChannelModule {
     // Security mirrors the message path: the access gate must return 'deliver'.
     // discord.js client is typed as `any` (dynamic import) so we narrow locally.
     interface ButtonInteraction {
+      id?: string;
       isButton?: () => boolean;
+      isChatInputCommand?: () => boolean;
+      commandName?: string;
+      options?: {getString(name:string):string|null};
+      deferUpdate?: () => Promise<unknown>;
+      deferReply?: (options: {ephemeral:boolean}) => Promise<unknown>;
+      deleteReply?: () => Promise<unknown>;
       customId?: string;
       guildId?: string | null;
       channelId: string;
@@ -401,6 +417,28 @@ export class DiscordModule implements ChannelModule {
     }
     this.client.on('interactionCreate', async (interaction: ButtonInteraction) => {
       try {
+        const orchButton=interaction.isButton?.()&&/^orch:[a-f0-9-]{36}$/.test(interaction.customId??'');
+        const slash=interaction.isChatInputCommand?.();
+        if(orchButton||slash){
+          const isDM=!interaction.guildId,isThread=interaction.channel?.isThread?.()??false;
+          const context:DiscordMessageContext={guildId:interaction.guildId??null,channelId:interaction.channelId,threadId:isThread?interaction.channelId:null,userId:interaction.user.id,username:interaction.user.username,messageId:interaction.message?.id??'',isDM,isThread,mentionsBot:true};
+          const access=gate(loadAccessFn(),context,saveAccessFn,()=>randomBytes(3).toString('hex'));
+          if(access.action!=='deliver'){await interaction.reply({content:'Not authorized.',ephemeral:true});return;}
+          if(orchButton)await interaction.deferUpdate?.();else await interaction.deferReply?.({ephemeral:true});
+          let text=orchButton?`/orch ${interaction.customId!.slice(5)}`:`/${interaction.commandName}`;
+          if(slash){
+            const name=interaction.commandName;
+            const arg=interaction.options?.getString(name==='voice'?'mode':name==='ask'?'question':'name');
+            if(name==='ask')text=arg??'';else if(arg)text+=' '+arg;
+            if(name==='cli'){
+              const channel=await this.client.channels.fetch(interaction.channelId);
+              await handleDiscordMessage({id:randomBytes(12).toString('hex'),content:'/cli',author:{id:interaction.user.id,username:interaction.user.username,bot:false},guild:interaction.guildId?{id:interaction.guildId}:null,guildId:interaction.guildId,channelId:interaction.channelId,channel,mentions:{has:()=>true}} as any);
+              await interaction.deleteReply?.();return;
+            }
+          }
+          await handler({channel:'discord',accountId:interaction.client.user?.id??'discord',senderId:interaction.user.id,chatId:interaction.channelId,chatType:isDM?'direct':'group',text,messageId:interaction.id??randomBytes(12).toString('hex'),controlMessageId:orchButton?interaction.message?.id:undefined,ts:Date.now()});
+          if(slash)await interaction.deleteReply?.();return;
+        }
         if (!interaction.isButton?.()) return;
 
         // `/cli` approve/deny — unlock (or reject) a pending terminal-viewer
@@ -518,7 +556,7 @@ export class DiscordModule implements ChannelModule {
         const typingFileDir = path.join(this.stateDir, 'typing');
         try {
           fs.mkdirSync(typingFileDir, { recursive: true });
-          fs.writeFileSync(path.join(typingFileDir, channelId), '');
+          if (process.env.GATEWAY_ORCHESTRATION_ENABLED !== 'true') fs.writeFileSync(path.join(typingFileDir, channelId), '');
         } catch {}
 
         const inbound: InboundMessage = {
@@ -621,6 +659,8 @@ export class DiscordModule implements ChannelModule {
   }
 
   private async processTypingSignals(typingDir: string, token: string): Promise<void> {
+    // Managed activity is derived from durable Agent/Worker state; stale legacy files are not work.
+    if (process.env.GATEWAY_ORCHESTRATION_ENABLED === 'true') return;
     let files: string[];
     try { files = fs.readdirSync(typingDir); } catch { return; }
 

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

@@ -7,8 +7,10 @@
 
 import { DiscordModule } from './module';
 import type { InboundMessage } from '../../types';
+import { ReceiverSpool } from '../receiver-spool';
 
 const CALLBACK_URL = process.env.CLAUDE_CHANNEL_CALLBACK;
+const spool = process.env.GATEWAY_ORCHESTRATION_INGRESS_DIR && CALLBACK_URL ? new ReceiverSpool(process.env.GATEWAY_ORCHESTRATION_INGRESS_DIR, CALLBACK_URL) : undefined;
 if (!CALLBACK_URL) {
   process.stderr.write('discord receiver: CLAUDE_CHANNEL_CALLBACK required\n');
   process.exit(1);
@@ -30,6 +32,14 @@ async function postCallback(inbound: InboundMessage): Promise<void> {
   if (inbound.attachmentFileId) {
     meta['attachment_file_id'] = inbound.attachmentFileId;
   }
+  if(inbound.attachments?.length)meta.attachments_json=JSON.stringify(inbound.attachments.map(a=>({ref:a.url,name:a.name,kind:a.kind,quoted:a.quoted})));
+  if(inbound.replyToMessageId)meta.replied_message_id=inbound.replyToMessageId;
+  if(inbound.repliedText)meta.replied_text=inbound.repliedText;
+  if(inbound.repliedSender)meta.replied_user=inbound.repliedSender;
+  if(inbound.threadId)meta.thread_ts=inbound.threadId;
+  if(inbound.attachmentKind)meta.attachment_kind=inbound.attachmentKind;
+  if(inbound.controlMessageId)meta.control_message_id=inbound.controlMessageId;
+  if (spool && !/^\/(voice|voices|tasks|stop|orch)(?:\s|$)/.test(inbound.text??'')) { spool.enqueue({ content: inbound.text ?? '', meta }); return; }
 
   try {
     await fetch(CALLBACK_URL!, {

package/mcp/tools/discord/types.ts

@@ -108,7 +108,10 @@ export interface DiscordMessage {
     parentId?: string | null;
   };
   createdTimestamp: number;
-  attachments: { first(): { url: string } | undefined };
+  reference?: {messageId?:string;channelId?:string};
+  fetchReference?(): Promise<DiscordMessage>;
+  flags?: number | {has(bit:number):boolean};
+  attachments: { first(): { url: string; contentType?: string | null; name?: string } | undefined; values?(): IterableIterator<{url:string;contentType?:string|null;name?:string}> };
   client: { user: { id: string } | null };
   startThread(options: { name: string; autoArchiveDuration: number }): Promise<{ id: string }>;
 }

package/mcp/tools/image/module.ts

@@ -735,7 +735,9 @@ export class ImageModule implements ToolModule {
           files,
           ...(artifacts ? { artifacts } : {}),
           ...(droppedImages > 0 ? { dropped_images: droppedImages } : {}),
-          note: 'Image saved. Deliver it to the user with your channel delivery tool — api_reply/reply (files: [...]), or line_image on LINE. Do NOT open/Read the file to inspect it first; attach it and answer briefly.'
+          note: (process.env.GATEWAY_ORCHESTRATION_ROLE === 'worker'
+            ? 'Image saved. Call task_stage_file for each output path, then finish this task. The agent orchestration engine owns user-facing delivery.'
+            : 'Image saved. Deliver it to the user with your channel delivery tool — api_reply/reply (files: [...]), or line_image on LINE. Do NOT open/Read the file to inspect it first; attach it and answer briefly.')
             + (model ? ` Mention which model made it (${model}).` : '')
             + (artifacts ? ' To edit this image later, reference it via its artifact_ref (e.g. image: "artifact:...").' : '')
             + (droppedImages > 0 ? ` (${droppedImages} extra image(s) beyond the cap were not saved)` : ''),

package/mcp/tools/receiver-spool.test.ts

@@ -0,0 +1,28 @@
+import { test, expect } from 'bun:test';
+import { mkdtempSync, readdirSync, rmSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ReceiverSpool } from './receiver-spool';
+
+test('receiver restart retains unacknowledged input and removes it only after gateway acceptance', async () => {
+  const root = mkdtempSync(join(tmpdir(), 'receiver-spool-'));
+  let fail = true;
+  const delivered: unknown[] = [];
+  const request = (async (_url: string | URL | Request, options?: RequestInit) => {
+    delivered.push(JSON.parse(String(options?.body)));
+    return new Response('', { status: fail ? 503 : 200 });
+  }) as typeof fetch;
+  let spool = new ReceiverSpool(root, 'http://fixture.invalid/channel', request);
+  try {
+    const input = { content: 'hello', meta: { chat_id: 'original', message_id: '1' } };
+    spool.enqueue(input);
+    await new Promise(resolve => setTimeout(resolve, 10));
+    const file = readdirSync(root).find(file => file.endsWith('.json'))!;
+    expect(JSON.parse(readFileSync(join(root, file), 'utf8'))).toEqual(input);
+    spool.close(); fail = false;
+    spool = new ReceiverSpool(root, 'http://fixture.invalid/channel', request);
+    await new Promise(resolve => setTimeout(resolve, 10));
+    expect(readdirSync(root)).toEqual([]);
+    expect(delivered.at(-1)).toEqual(input);
+  } finally { spool.close(); rmSync(root, { recursive: true, force: true }); }
+});

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};
+}