@0xmaxma/claude-gateway 2.0.3 → 2.0.5

package/mcp/lazy-tools.ts

@@ -0,0 +1,41 @@
+import type { McpToolDefinition, McpToolResult } from './types';
+
+export const LAZY_TOOL_DEFINITIONS: McpToolDefinition[] = [
+  { name: 'tool_search', description: 'Discover available gateway capabilities. Empty query lists tool names and descriptions; search by query or exact name to retrieve original argument schemas before calling tool_call. Results are paginated. This catalog contains only tools authorized for this worker.',
+    inputSchema: { type: 'object', properties: { query: { type: 'string' }, name: { type: 'string' }, offset: { type: 'integer', minimum: 0 }, limit: { type: 'integer', minimum: 1, maximum: 20 }, include_schema: { type: 'boolean' } }, additionalProperties: false } },
+  { name: 'tool_call', description: 'Execute a gateway capability discovered with tool_search. Use its exact name and original arguments. All original permissions, validation and cancellation apply. Task reporting and memory retrieval remain directly available.',
+    inputSchema: { type: 'object', properties: { name: { type: 'string' }, arguments: { type: 'object' } }, required: ['name', 'arguments'], additionalProperties: false } },
+];
+
+const fail = (text: string): McpToolResult => ({ content: [{ type: 'text', text }], isError: true });
+const result = (value: unknown): McpToolResult => ({ content: [{ type: 'text', text: JSON.stringify(value) }] });
+
+/** Discovery is data-only. Invocation delegates to the SAME dispatcher as direct calls. */
+export function createLazyToolCatalog(tools: readonly McpToolDefinition[], excludeReserved = true) {
+  const reserved = new Set(LAZY_TOOL_DEFINITIONS.map(tool => tool.name));
+  const catalog = [...tools].filter(tool => !excludeReserved || !reserved.has(tool.name))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const names = new Set(catalog.map(tool => tool.name));
+  return {
+    search(args: Record<string, unknown>): McpToolResult {
+      if ((args.query !== undefined && typeof args.query !== 'string') ||
+          (args.name !== undefined && typeof args.name !== 'string') ||
+          (args.include_schema !== undefined && typeof args.include_schema !== 'boolean')) return fail('Invalid search arguments');
+      const offset = args.offset ?? 0; const limit = args.limit ?? 5;
+      if (typeof offset !== 'number' || !Number.isSafeInteger(offset) || offset < 0 ||
+          typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > 20) return fail('Invalid search pagination');
+      const query = String(args.query ?? '').trim().toLowerCase();
+      const name = String(args.name ?? '').trim().toLowerCase();
+      const matches = catalog.filter(tool => name ? tool.name.toLowerCase() === name :
+        query.split(/\s+/).every(word => `${tool.name} ${tool.description}`.toLowerCase().includes(word)));
+      const schemas = args.include_schema ?? Boolean(query || name);
+      return result({ total: matches.length, offset, next_offset: offset + limit < matches.length ? offset + limit : null,
+        tools: matches.slice(offset, offset + limit).map(tool => schemas ? tool : { name: tool.name, description: tool.description }) });
+    },
+    async call(args: Record<string, unknown>, dispatch: (name: string, input: Record<string, unknown>) => Promise<McpToolResult>): Promise<McpToolResult> {
+      if (typeof args.name !== 'string' || !names.has(args.name)) return fail('Unknown or unauthorized gateway tool');
+      if (!args.arguments || typeof args.arguments !== 'object' || Array.isArray(args.arguments)) return fail('Tool arguments must be an object');
+      return dispatch(args.name, args.arguments as Record<string, unknown>);
+    },
+  };
+}

package/mcp/server.ts

@@ -14,6 +14,7 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 import { gatewayModules } from './modules';
 import { AGENT_TASK_TOOLS, WORKER_REPORT_TOOLS, callTaskBridge } from './tools/tasks/module';
+import { createLazyToolCatalog, LAZY_TOOL_DEFINITIONS } from './lazy-tools';
 import { buildChannelInstructions } from './instructions';
 import type { ChannelModule, ToolModule, McpToolDefinition } from './types';
 
@@ -52,9 +53,23 @@ for (const mod of modules) {
   }
 }
 
-const taskTools = ORCHESTRATION_ROLE === 'agent' ? AGENT_TASK_TOOLS.filter(tool => (tool.name !== 'conversation_intake' || process.env.GATEWAY_SEMANTIC_INTAKE === 'true') && (tool.name !== 'capabilities_list' || process.env.GATEWAY_CAPABILITY_CATALOG === 'true')) : ORCHESTRATION_ROLE === 'worker' ? WORKER_REPORT_TOOLS.filter(tool => tool.name !== 'task_memory_append' || process.env.GATEWAY_ORCHESTRATION_WRITE_MEMORY === 'true') : [];
+// conversation_intake is declared on every agent turn, whatever the semantic-intake feature
+// state. The advertised tool list is position 0 of Anthropic's cached [tools, system, messages]
+// prefix, and the feature is decided per turn (runtime.ts computes it from the flag AND from
+// whether this turn is a notification), so filtering the declaration here re-wrote the prefix
+// mid-session and invalidated the whole cache — the same defect ee800a7 fixed for the response
+// schema. The turn's INTAKE_OVERLAY prompt text, below the cache breakpoint, is what asks for
+// the tool; the bridge refuses the call outright when the feature is not active.
+const taskTools = ORCHESTRATION_ROLE === 'agent' ? AGENT_TASK_TOOLS.filter(tool => tool.name !== 'capabilities_list' || process.env.GATEWAY_CAPABILITY_CATALOG === 'true') : ORCHESTRATION_ROLE === 'worker' ? WORKER_REPORT_TOOLS.filter(tool => tool.name !== 'task_memory_append' || process.env.GATEWAY_ORCHESTRATION_WRITE_MEMORY === 'true') : [];
 if (ORCHESTRATION_ROLE && process.env.GATEWAY_ORCHESTRATION_TICKET_FILE) visibleTools.push(...taskTools);
 
+// Preserve the full policy-filtered inventory internally; only schema exposure is lazy.
+const lazyEnabled = ORCHESTRATION_ROLE === 'worker' && process.env.GATEWAY_LAZY_TOOLS === 'true';
+const deferredTools = visibleTools.filter(tool => toolMap.has(tool.name) && !['memory_search','memory_get'].includes(tool.name));
+const deferredNames = new Set(deferredTools.map(tool => tool.name));
+const lazyCatalog = createLazyToolCatalog(deferredTools);
+const advertisedTools = lazyEnabled ? [...visibleTools.filter(tool => !deferredNames.has(tool.name)), ...LAZY_TOOL_DEFINITIONS] : visibleTools;
+
 // Initialize channel modules so their bot API clients are ready for tool calls.
 // initBot() returns immediately after creating the client — no blocking.
 for (const mod of modules) {
@@ -79,47 +94,51 @@ const mcp = new Server(
         'claude/channel/permission': {},
       },
     },
-    instructions: ORCHESTRATION_ROLE ? 'Use scoped capability discovery, task tools and memory retrieval. The agent writes user-facing responses; workers return task results and orchestration handles delivery.' : buildChannelInstructions(imageEnabled, videoEnabled),
+    instructions: ORCHESTRATION_ROLE ? 'Use scoped capability discovery, task tools and memory retrieval. The agent writes user-facing responses; workers return task results and orchestration handles delivery.' + (lazyEnabled ? ' Gateway execution capabilities are available through tool_search and tool_call: search for the capability to read its original arguments, then invoke it by exact name. An unlisted execution tool is not unavailable; inspect the catalog. Task reporting and memory retrieval remain direct tools.' : '') : buildChannelInstructions(imageEnabled, videoEnabled),
   },
 );
 
 mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
-  tools: visibleTools,
+  tools: advertisedTools,
 }));
 
 mcp.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
-  const toolName = req.params.name;
+  const dispatch = async (toolName: string, args: Record<string, unknown>) => {
+    if (ORCHESTRATION_ROLE && process.env.GATEWAY_ORCHESTRATION_TICKET_FILE && taskTools.some(tool => tool.name === toolName)) {
+      return callTaskBridge(toolName, args, String(extra.requestId), AbortSignal.any([extra.signal, shutdownController.signal]));
+    }
+
+    const mod = toolMap.get(toolName);
+    if (!mod) {
+      return {
+        content: [{ type: 'text', text: `unknown tool: ${toolName}` }],
+        isError: true,
+      };
+    }
+    if (ORCHESTRATION_ROLE === 'worker' && process.env.GATEWAY_ORCHESTRATION_MEDIA === 'true') {
+      const validation = await callTaskBridge('task_validate', {}, String(extra.requestId), AbortSignal.any([extra.signal, shutdownController.signal]));
+      if (validation.isError) return validation;
+    }
+
+    // extra.signal fires on notifications/cancelled for THIS call (the SDK matches
+    // it by requestId) — the CLI sends that when a user Stop/Ctrl-C interrupts an
+    // in-flight tool call. Threaded through so a long-running module (image
+    // generation's poll loop) can react instead of running to its full timeout.
+    // Also combine with shutdownController.signal: the CLI sending that
+    // notification is only a "SHOULD" in the MCP spec, not a "MUST", and in
+    // practice a Stop that lets the CLI process exit cleanly (rather than
+    // staying alive to keep chatting) closes this server's stdin without ever
+    // sending notifications/cancelled — extra.signal would then never fire, and
+    // an in-flight image generation would poll to its full timeout instead of
+    // cancelling. stdin closing is a reliable, protocol-independent signal that
+    // the turn is over either way, so it backstops the notification.
+    const combinedSignal = AbortSignal.any([extra.signal, shutdownController.signal]);
+    return mod.handleTool(toolName, args, combinedSignal);
+  };
   const args = (req.params.arguments ?? {}) as Record<string, unknown>;
-  if (ORCHESTRATION_ROLE && process.env.GATEWAY_ORCHESTRATION_TICKET_FILE && taskTools.some(tool => tool.name === toolName)) {
-    return callTaskBridge(toolName, args, String(extra.requestId), AbortSignal.any([extra.signal, shutdownController.signal]));
-  }
-
-  const mod = toolMap.get(toolName);
-  if (!mod) {
-    return {
-      content: [{ type: 'text', text: `unknown tool: ${toolName}` }],
-      isError: true,
-    };
-  }
-  if (ORCHESTRATION_ROLE === 'worker' && process.env.GATEWAY_ORCHESTRATION_MEDIA === 'true') {
-    const validation = await callTaskBridge('task_validate', {}, String(extra.requestId), AbortSignal.any([extra.signal, shutdownController.signal]));
-    if (validation.isError) return validation;
-  }
-
-  // extra.signal fires on notifications/cancelled for THIS call (the SDK matches
-  // it by requestId) — the CLI sends that when a user Stop/Ctrl-C interrupts an
-  // in-flight tool call. Threaded through so a long-running module (image
-  // generation's poll loop) can react instead of running to its full timeout.
-  // Also combine with shutdownController.signal: the CLI sending that
-  // notification is only a "SHOULD" in the MCP spec, not a "MUST", and in
-  // practice a Stop that lets the CLI process exit cleanly (rather than
-  // staying alive to keep chatting) closes this server's stdin without ever
-  // sending notifications/cancelled — extra.signal would then never fire, and
-  // an in-flight image generation would poll to its full timeout instead of
-  // cancelling. stdin closing is a reliable, protocol-independent signal that
-  // the turn is over either way, so it backstops the notification.
-  const combinedSignal = AbortSignal.any([extra.signal, shutdownController.signal]);
-  return mod.handleTool(toolName, args, combinedSignal);
+  if (lazyEnabled && req.params.name === 'tool_search') return lazyCatalog.search(args);
+  if (lazyEnabled && req.params.name === 'tool_call') return lazyCatalog.call(args, dispatch);
+  return dispatch(req.params.name, args);
 });
 
 // Connect MCP transport

package/mcp/tools/discord/commands.ts

@@ -11,6 +11,8 @@ export const SLASH_COMMANDS: SlashCommandDef[] = [
     description: 'Ask the agent a question',
     options: [{ name: 'question', description: 'Your question', required: true, type: 'STRING' }],
   },
+  { name: 'clear', description: 'Reset model context without deleting chat history' },
+  { name: 'compact', description: 'Compact Claude Code context without changing chat history' },
   { name: 'session', description: 'Show current session info' },
   {
     name: 'new',

package/mcp/tools/discord/inbound.ts

@@ -49,7 +49,7 @@ export function createMessageHandler(
       ts: message.createdTimestamp,
     };
 
-    const attachments = (msg: DiscordMessage, quoted=false) => (msg.attachments.values ? [...msg.attachments.values()] : [msg.attachments.first()].filter(Boolean)).slice(0,10).map(a=>({url:a!.url,name:a!.name,kind:a!.contentType?.startsWith('image/')?'image':a!.contentType?.startsWith('audio/')?'audio':'file',quoted}));
+    const attachments = (msg: DiscordMessage, quoted=false) => (msg.attachments.values ? [...msg.attachments.values()] : [msg.attachments.first()].filter(Boolean)).slice(0,10).map(a=>({url:a!.url,name:a!.name,size:a!.size,kind:a!.contentType?.startsWith('image/')?'image':a!.contentType?.startsWith('audio/')?'audio':'file',quoted}));
     inbound.attachments = attachments(message);
     if (message.reference?.messageId && (!message.reference.channelId || message.reference.channelId === message.channelId)) {
       inbound.replyToMessageId = message.reference.messageId;

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

@@ -32,7 +32,7 @@ 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.attachments?.length)meta.attachments_json=JSON.stringify(inbound.attachments.map(a=>({ref:a.url,name:a.name,kind:a.kind,quoted:a.quoted,size:a.size})));
   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;

package/mcp/tools/discord/types.ts

@@ -111,7 +111,7 @@ export interface DiscordMessage {
   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}> };
+  attachments: { first(): { url: string; contentType?: string | null; name?: string; size?: number } | undefined; values?(): IterableIterator<{url:string;contentType?:string|null;name?:string;size?:number}> };
   client: { user: { id: string } | null };
   startThread(options: { name: string; autoArchiveDuration: number }): Promise<{ id: string }>;
 }

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

@@ -1,4 +1,4 @@
-import { test, expect } from 'bun:test';
+import { test, expect, spyOn } from 'bun:test';
 import { mkdtempSync, readdirSync, rmSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -6,6 +6,8 @@ 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 now = Date.now();
+  const clock = spyOn(Date, 'now').mockImplementation(() => now);
   let fail = true;
   const delivered: unknown[] = [];
   const request = (async (_url: string | URL | Request, options?: RequestInit) => {
@@ -22,7 +24,11 @@ test('receiver restart retains unacknowledged input and removes it only after ga
     spool.close(); fail = false;
     spool = new ReceiverSpool(root, 'http://fixture.invalid/channel', request);
     await new Promise(resolve => setTimeout(resolve, 10));
+    expect(delivered).toHaveLength(1);
+    expect(readdirSync(root).filter(file => file.endsWith('.json'))).toHaveLength(1);
+    now += 1000;
+    await spool.flush();
     expect(readdirSync(root)).toEqual([]);
     expect(delivered.at(-1)).toEqual(input);
-  } finally { spool.close(); rmSync(root, { recursive: true, force: true }); }
+  } finally { clock.mockRestore(); spool.close(); rmSync(root, { recursive: true, force: true }); }
 });

package/mcp/tools/receiver-spool.ts

@@ -1,55 +1,228 @@
 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 { mkdirSync, readdirSync, openSync, closeSync, writeFileSync, fsyncSync, renameSync, readFileSync, unlinkSync, statSync, existsSync } 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. */
+type RetryState = { queuedAt: number; attempts: number; nextAttemptAt: number; recoveryBatch?: string; sealedMessageIds?: string[] };
+type Entry = { file: string; payload: string; input: ChannelInput; modified: number; state: RetryState; albumMessageIds?: string[] };
+const MAX_BACKOFF_MS = 5 * 60_000;
+const STALE_STARTUP_AGE_MS = 5 * 60_000;
+
+/** Persist raw provider payloads until SQLite admission. Retry state is separate
+ * so old journals remain readable and provider deduplication identities stay intact. */
 export class ReceiverSpool {
   private active = false;
+  private cursor = 0;
+  private lastQueuedAt = 0;
+  private reportedInvalidEntry = 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.pruneAlbumReceipts();
+    const snapshot = this.entries();
+    this.lastQueuedAt = Math.max(0, ...snapshot.map(entry => entry.state.queuedAt));
+    const batches = new Map<string, string>();
+    for (const entry of snapshot) {
+      if (entry.state.recoveryBatch) batches.set(this.conversation(entry.input), entry.state.recoveryBatch);
+    }
+    for (const entry of snapshot) {
+      const conversation = this.conversation(entry.input);
+      if (Date.now() - entry.state.queuedAt > STALE_STARTUP_AGE_MS && !batches.has(conversation)) batches.set(conversation, randomUUID());
+    }
+    // Quarantine the entire startup conversation, including its newer tail.
+    // Persist the batch before sending anything so retries/restarts share one notice.
+    for (const entry of snapshot) {
+      const batch = batches.get(this.conversation(entry.input));
+      if (batch) this.saveState(entry.file, { ...entry.state, recoveryBatch: batch });
+    }
     this.timer = setInterval(() => { void this.flush(); }, 1000); this.timer.unref();
     void this.flush();
   }
+  private conversation(input: ChannelInput): string {
+    const m = input?.meta ?? {};
+    return JSON.stringify([m.source ?? m.channel ?? '', m.account_id ?? '', m.chat_id ?? '', m.message_thread_id ?? m.thread_id ?? m.thread_ts ?? '']);
+  }
+  private atomicWrite(file: string, payload: string): void {
+    const temporary = join(this.directory, `${randomUUID()}.tmp`);
+    const descriptor = openSync(temporary, 'wx', 0o600);
+    try { writeFileSync(descriptor, payload); fsyncSync(descriptor); } finally { closeSync(descriptor); }
+    renameSync(temporary, join(this.directory, file));
+    this.syncDirectory();
+  }
+  private state(file: string, queuedAt: number): RetryState {
+    try {
+      const state = JSON.parse(readFileSync(join(this.directory, `${file}.retry`), 'utf8')) as RetryState;
+      const timestamp = (value: number) => Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER;
+      if (!state || !timestamp(state.queuedAt) || !timestamp(state.nextAttemptAt)
+        || !Number.isSafeInteger(state.attempts) || state.attempts < 0
+        || (state.sealedMessageIds !== undefined && (!Array.isArray(state.sealedMessageIds) || state.sealedMessageIds.length > 10 || state.sealedMessageIds.some(id => typeof id !== 'string' || !id)))
+        || (state.recoveryBatch !== undefined && (typeof state.recoveryBatch !== 'string' || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(state.recoveryBatch)))) {
+        throw new Error('Invalid ingress retry state');
+      }
+      return state;
+    }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      return { queuedAt, attempts: 0, nextAttemptAt: 0 };
+    }
+  }
+  private saveState(file: string, state: RetryState): void { this.atomicWrite(`${file}.retry`, JSON.stringify(state)); }
+  private entries(): Entry[] {
+    const entries: Entry[] = [];
+    const blocked = new Set<string>();
+    for (const file of readdirSync(this.directory).filter(file => /^[a-f0-9]{64}\.json$/.test(file))) {
+      let input: ChannelInput | undefined;
+      try {
+        const location = join(this.directory, file);
+        const modified = statSync(location).mtimeMs;
+        const payload = readFileSync(location, 'utf8');
+        input = JSON.parse(payload) as ChannelInput;
+        if (!input || typeof input !== 'object' || typeof input.content !== 'string'
+          || !input.meta || typeof input.meta !== 'object' || Array.isArray(input.meta)
+          || Object.values(input.meta).some(value => typeof value !== 'string')) {
+          input = undefined;
+          throw new Error('Invalid ingress payload');
+        }
+        // Validate nested album metadata inside the per-record boundary, so a
+        // damaged album cannot abort delivery for unrelated conversations.
+        let albumMessageIds: string[] | undefined;
+        if (mediaGroupKey(input)) {
+          const ids: unknown = JSON.parse(input.meta.message_ids_json);
+          if (!Array.isArray(ids) || !ids.length || ids.length > 10 || ids.some(id=>typeof id !== 'string' || !id)) {
+            throw new Error('Invalid ingress album members');
+          }
+          albumMessageIds = ids;
+        }
+        entries.push({ file, modified, payload, input, state: this.state(file, modified), albumMessageIds });
+      } catch {
+        // An identifiable conversation must not skip its damaged head. Other
+        // conversations remain usable; preserve all bytes for operator recovery.
+        if (input) blocked.add(this.conversation(input));
+        if (!this.reportedInvalidEntry) {
+          this.reportedInvalidEntry = true;
+          process.stderr.write('Receiver spool retained an unreadable or invalid entry; inspect the local journal.\n');
+        }
+      }
+    }
+    return entries.filter(entry => !blocked.has(this.conversation(entry.input)))
+      .sort((a, b) => a.state.queuedAt - b.state.queuedAt || a.file.localeCompare(b.file));
+  }
+
   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 group = mediaGroupKey(input as ChannelInput);
+    let albumKey = group;
+    if (group) {
+      const messageId = (input as ChannelInput).meta.message_id;
+      const initial = this.state(`${group}.json`, Date.now());
+      if (initial.sealedMessageIds) {
+        if (initial.sealedMessageIds.includes(messageId)) return;
+        // An attempted body is immutable: late members use their own stable
+        // first-message identity, never an expanded body under an existing ID.
+        albumKey = createHash('sha256').update(JSON.stringify([group, messageId])).digest('hex');
+      }
+      const target = `${albumKey}.json`;
+      const state = this.state(target, Date.now());
+      if (state.sealedMessageIds?.includes(messageId)) return;
+      let prior: ChannelInput | undefined;
+      try { prior = JSON.parse(readFileSync(join(this.directory, target), 'utf8')); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+      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();
+    const key = albumKey ?? createHash('sha256').update(payload).digest('hex');
+    const file = `${key}.json`;
+    const location = join(this.directory, file);
+    const present = existsSync(location);
+    if (!present && readdirSync(this.directory).filter(file => file.endsWith('.json')).length >= 1000) throw new Error('Ingress spool full');
+    // Preserve admission order even when an album's quiet window is reset.
+    const queuedAt = present ? statSync(location).mtimeMs : Math.max(Date.now(), this.lastQueuedAt + 0.01);
+    const state = this.state(file, queuedAt);
+    this.lastQueuedAt = Math.max(this.lastQueuedAt, state.queuedAt);
+    this.saveState(file, state);
+    this.atomicWrite(file, payload);
     void this.flush();
   }
+  private pruneAlbumReceipts(): void {
+    const receipts = readdirSync(this.directory).filter(file => /^[a-f0-9]{64}\.json\.retry$/.test(file)
+      && !existsSync(join(this.directory, file.slice(0, -6))))
+      .map(file => ({ file, modified: statSync(join(this.directory, file)).mtimeMs }))
+      .sort((a, b) => b.modified - a.modified);
+    let changed = false;
+    for (const [index, receipt] of receipts.entries()) {
+      if (index < 1000 && Date.now() - receipt.modified < 24 * 60 * 60_000) continue;
+      // Do not remove an unknown/corrupt sidecar as part of receipt cleanup.
+      try {
+        if (!this.state(receipt.file.slice(0, -6), receipt.modified).sealedMessageIds) continue;
+        unlinkSync(join(this.directory, receipt.file)); changed = true;
+      } catch { /* Preserve unrecognized bytes for operator recovery. */ }
+    }
+    if (changed) this.syncDirectory();
+  }
   private syncDirectory(): void {
     const descriptor = openSync(this.directory, 'r');
     try { fsyncSync(descriptor); } finally { closeSync(descriptor); }
   }
+  private defer(entry: Entry, response?: Response): void {
+    const attempts = Math.min(Number.MAX_SAFE_INTEGER, entry.state.attempts + 1);
+    const exponential = Math.min(MAX_BACKOFF_MS, 1000 * 2 ** Math.min(attempts - 1, 9));
+    const header = response?.headers.get('retry-after');
+    const retryAfter = header ? (/^\d+(\.\d+)?$/.test(header) ? Number(header) * 1000 : Date.parse(header) - Date.now()) : 0;
+    // Bound our exponential policy; honor a longer server-requested pause.
+    const delay = Math.max(exponential, Number.isFinite(retryAfter) ? Math.min(24 * 60 * 60_000, retryAfter) : 0);
+    this.saveState(entry.file, { ...entry.state, attempts, nextAttemptAt: Date.now() + delay });
+  }
   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();}
+      const conversations = new Map<string, Entry[]>();
+      for (const entry of this.entries()) {
+        const conversation = this.conversation(entry.input);
+        const entries = conversations.get(conversation) ?? [];
+        entries.push(entry);
+        conversations.set(conversation, entries);
+      }
+      const groups = [...conversations.values()];
+      // Rotate conversation heads, then drain successful conversations round-robin.
+      // Failed/waiting heads block only their own ordered tail.
+      const start = this.cursor % Math.max(groups.length, 1);
+      this.cursor = start + Math.min(100, groups.length);
+      const pending = [...groups.slice(start), ...groups.slice(0, start)];
+      let attempts = 0;
+      while (pending.length && attempts < 100) {
+        const group = pending.shift()!;
+        const entry = group.shift()!;
+        if (entry.state.nextAttemptAt > Date.now()) continue;
+        // Another callback may have yielded while this unsealed album grew.
+        // Refresh its full body and quiet window next pass before sealing it.
+        if (readFileSync(join(this.directory, entry.file), 'utf8') !== entry.payload) continue;
+        if (mediaGroupKey(entry.input) && Date.now() - entry.modified < this.mediaGroupWaitMs) continue;
+        const body = entry.state.recoveryBatch ? JSON.stringify({ ...entry.input, meta: { ...entry.input.meta, ingress_recovery_batch: entry.state.recoveryBatch } }) : entry.payload;
+        if (entry.albumMessageIds && !entry.state.sealedMessageIds) {
+          entry.state = { ...entry.state, sealedMessageIds: entry.albumMessageIds };
+          this.saveState(entry.file, entry.state);
+        }
+        attempts++;
+        let response: Response;
+        try {
+          response = await this.request(this.callback, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body, signal: AbortSignal.timeout(10000) });
+        } catch { this.defer(entry); continue; }
+        if (!response.ok) { this.defer(entry, response); continue; }
+        const location = join(this.directory, entry.file);
+        if (readFileSync(location, 'utf8') === entry.payload) {
+          unlinkSync(location);
+          const retry = join(this.directory, `${entry.file}.retry`);
+          // Pending retries never expire. Acknowledged album receipts retain
+          // member IDs for bounded platform-redelivery deduplication.
+          if (entry.state.sealedMessageIds) this.saveState(entry.file, { ...entry.state, attempts: 0, nextAttemptAt: 0 });
+          else if (existsSync(retry)) unlinkSync(retry);
+          this.syncDirectory();
+          if (entry.state.sealedMessageIds) this.pruneAlbumReceipts();
+          if (group.length) pending.push(group);
+        }
       }
-    } catch { /* persisted message is retried on next tick or process restart */ }
+    } catch { /* Keep persisted input on filesystem failure. */ }
     finally { this.active = false; }
   }
   close(): void { clearInterval(this.timer); }

package/mcp/tools/tasks/module.ts

@@ -5,18 +5,7 @@ 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_question', description: 'Manage pending questions without answering or resuming work. Ask stages one natural separate message after your reply; discuss marks ongoing consultation; defer/mute/resume persist the user reminder preference.', inputSchema: schema({ action: { type: 'string', enum: ['ask','discuss','defer','mute','resume'] }, question_ids: { type: 'array', items: text, minItems: 1, maxItems: 20 }, text, delay_ms: { type: 'integer', minimum: 60000, maximum: 2592000000 } }, ['action', 'question_ids']) },
-  { 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 { AGENT_TASK_TOOLS } from '../../../dist/orchestration/agent-tool-schemas.js';
 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 }, []) },

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

@@ -9,12 +9,12 @@ export function mergeMediaGroup(prior:ChannelInput|undefined,input: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});
+ const parts:Array<{id:string;caption:string;ref?:string;path?:string;name?:string;size?:number}> = 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,size:input.meta.attachment_size===undefined?undefined:Number(input.meta.attachment_size)});
  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})))};
+  attachments_json:JSON.stringify(parts.map(({ref,path,name,size})=>({ref,path,name,size})))};
  // 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};