@0xmaxma/claude-gateway 2.0.4 → 2.0.6

package/mcp/lazy-tools.test.ts

@@ -0,0 +1,152 @@
+import { describe, test, expect } from 'bun:test';
+import { createLazyToolCatalog } from './lazy-tools';
+import type { McpToolDefinition } from './types';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const defs: McpToolDefinition[] = Array.from({ length: 23 }, (_, i) => ({ name: `tool_${String(i).padStart(2, '0')}`, description: `Original description ${i}`,
+  inputSchema: { type: 'object', properties: { target: { type: 'string', enum: ['a', 'b'] } }, required: ['target'], additionalProperties: false } }));
+const parse = (r: ReturnType<ReturnType<typeof createLazyToolCatalog>['search']>) => JSON.parse(r.content[0].text);
+
+describe('lazy gateway tools', () => {
+  test('bounded discovery lists all metadata and exact original schemas on demand', () => {
+    const catalog = createLazyToolCatalog(defs);
+    const index = parse(catalog.search({ limit: 20 }));
+    expect(index.total).toBe(23); expect(index.next_offset).toBe(20);
+    expect(index.tools[0]).toEqual({ name: defs[0].name, description: defs[0].description });
+    expect(parse(catalog.search({ offset: 20 })).tools).toHaveLength(3);
+    expect(parse(catalog.search({ name: 'TOOL_01' })).tools).toEqual([defs[1]]);
+    expect(parse(catalog.search({ query: 'ORIGINAL description 22' })).tools).toEqual([defs[22]]);
+    expect(catalog.search({ limit: 21 }).isError).toBe(true);
+  });
+  test('unauthorized, task and recursive tools never reach dispatcher', async () => {
+    let calls = 0; const dispatch = async () => { calls++; return { content: [] }; };
+    const catalog = createLazyToolCatalog(defs);
+    for (const name of ['missing', 'task_spawn', 'tool_call', 'tool_search']) expect((await catalog.call({ name, arguments: {} }, dispatch)).isError).toBe(true);
+    expect((await catalog.call({ name: 'tool_00', arguments: [] }, dispatch)).isError).toBe(true);
+    expect(calls).toBe(0);
+  });
+  test('excludeReserved filters an underlying tool literally named tool_search/tool_call; the connector opt-out does not', async () => {
+    const collision: McpToolDefinition[] = [...defs,
+      { name: 'tool_search', description: 'Underlying tool that collides with the reserved name', inputSchema: { type: 'object', properties: {}, additionalProperties: false } }];
+    let calls = 0; const dispatch = async () => { calls++; return { content: [] }; };
+    const filtered = createLazyToolCatalog(collision);
+    expect(parse(filtered.search({ name: 'tool_search' })).total).toBe(0);
+    expect((await filtered.call({ name: 'tool_search', arguments: {} }, dispatch)).isError).toBe(true);
+    expect(calls).toBe(0);
+    const unfiltered = createLazyToolCatalog(collision, false);
+    expect(parse(unfiltered.search({ name: 'tool_search' })).total).toBe(1);
+    expect((await unfiltered.call({ name: 'tool_search', arguments: {} }, dispatch)).isError).toBeFalsy();
+    expect(calls).toBe(1);
+  });
+  test('preserves original arguments, validation errors and cancellation through dispatcher', async () => {
+    const catalog = createLazyToolCatalog(defs), args = { target: 'invalid' };
+    const denial = { isError: true, content: [{ type: 'text' as const, text: 'original validation rejected target' }] };
+    expect(await catalog.call({ name: 'tool_00', arguments: args }, async (name, actual) => {
+      expect(name).toBe('tool_00'); expect(actual).toBe(args); return denial;
+    })).toBe(denial);
+    const controller = new AbortController(); controller.abort();
+    await expect(catalog.call({ name: 'tool_00', arguments: {} }, async () => { controller.signal.throwIfAborted(); return denial; })).rejects.toThrow();
+  });
+  test('real MCP worker facade preserves ticket validation for direct and wrapped calls', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'gateway-lazy-'));
+    const requests: string[] = [];
+    const bridge = Bun.serve({ hostname: '127.0.0.1', port: 0, async fetch(req) {
+      requests.push((await req.json()).tool);
+      return new Response('TASK_TICKET_REVOKED', { status: 403 });
+    } });
+    const ticket = join(dir, 'ticket.json');
+    writeFileSync(ticket, JSON.stringify({ url: `http://127.0.0.1:${bridge.port}`, token: 'test-only' }));
+    const client = new Client({ name: 'lazy-test', version: '1' });
+    const transport = new StdioClientTransport({ command: 'bun', args: [join(import.meta.dir, 'server.ts')], stderr: 'ignore', env: {
+      PATH: process.env.PATH ?? '', HOME: dir, GATEWAY_ORCHESTRATION_ROLE: 'worker', GATEWAY_ORCHESTRATION_MEDIA: 'true',
+      GATEWAY_LAZY_TOOLS: 'true', GATEWAY_ORCHESTRATION_TICKET_FILE: ticket, IMAGE_DISABLED: 'true', VIDEO_DISABLED: 'true',
+    } });
+    try {
+      await client.connect(transport);
+      const list = await client.listTools();
+      expect(list.tools.some(t => t.name === 'tool_search')).toBe(true);
+      expect(list.tools.some(t => t.name === 'browser_navigate')).toBe(false);
+      expect(list.tools.some(t => t.name === 'task_report_progress')).toBe(true);
+      const found = await client.callTool({ name: 'tool_search', arguments: { name: 'browser_navigate' } });
+      expect(JSON.parse((found.content as Array<{ text: string }>)[0].text).tools[0].inputSchema).toBeDefined();
+      for (const call of [{ name: 'browser_navigate', arguments: { url: 'https://example.test' } },
+        { name: 'tool_call', arguments: { name: 'browser_navigate', arguments: { url: 'https://example.test' } } }]) {
+        const response = await client.callTool(call);
+        expect(response.isError).toBe(true);
+        expect((response.content as Array<{ text: string }>)[0].text).toBe('TASK_TICKET_REVOKED');
+      }
+      expect(requests).toEqual(['task_validate', 'task_validate']);
+    } finally { await client.close(); bridge.stop(true); rmSync(dir, { recursive: true, force: true }); }
+  }, 15000);
+});
+
+test('real lazy inventory preserves every execution schema and successful browser behavior', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'gateway-lazy-smoke-'));
+  const browserCalls: unknown[] = [], bridgeCalls: unknown[] = [];
+  const browserResult = { content: [{ type: 'text', text: JSON.stringify({ title: 'Stub page', status: 'ready' }) }] };
+  const local = Bun.serve({ hostname: '127.0.0.1', port: 0, async fetch(req) {
+    const body = await req.json();
+    if (new URL(req.url).pathname === '/ticket') {
+      bridgeCalls.push(body); return Response.json({ valid: true });
+    }
+    if (new URL(req.url).pathname === '/mcp') {
+      browserCalls.push(body);
+      return new Response(`data: ${JSON.stringify({ jsonrpc: '2.0', id: body.id, result: browserResult })}\n\n`, { headers: { 'Content-Type': 'text/event-stream' } });
+    }
+    throw new Error('Unexpected network call: ' + req.url);
+  } });
+  const base = `http://127.0.0.1:${local.port}`, ticket = join(dir, 'ticket.json');
+  writeFileSync(ticket, JSON.stringify({ url: base + '/ticket', token: 'synthetic-only' }));
+  const common = { PATH: process.env.PATH ?? '', HOME: dir, GATEWAY_ORCHESTRATION_ROLE: 'worker', GATEWAY_ORCHESTRATION_MEDIA: 'true',
+    GATEWAY_ORCHESTRATION_TICKET_FILE: ticket, GETPOD_BROWSER_URL: base, GETPOD_BROWSER_API_KEY: 'synthetic-only',
+    ANTHROPIC_BASE_URL: base, ANTHROPIC_AUTH_TOKEN: 'synthetic-only', GATEWAY_SESSION_ID: 'synthetic-session', GATEWAY_AGENT_ID: 'synthetic-agent' };
+  const clients: Client[] = [];
+  const start = performance.now();
+  try {
+    for (const lazy of [false, true]) {
+      const client = new Client({ name: 'local-inventory-smoke', version: '1' }); clients.push(client);
+      await client.connect(new StdioClientTransport({ command: 'bun', args: [join(import.meta.dir, 'server.ts')], stderr: 'ignore',
+        env: { ...common, GATEWAY_LAZY_TOOLS: String(lazy) } }));
+    }
+    const readyMs = performance.now() - start;
+    const direct = (await clients[0].listTools()).tools, lazy = (await clients[1].listTools()).tools;
+    const execution = direct.filter(tool => !lazy.some(other => other.name === tool.name));
+    expect(execution.map(t => t.name)).toContain('generate_image');
+    expect(execution.map(t => t.name)).toContain('generate_video');
+    const searchStart = performance.now();
+    for (const tool of execution) {
+      const found = await clients[1].callTool({ name: 'tool_search', arguments: { name: tool.name } });
+      const entry = JSON.parse((found.content as Array<{ text: string }>)[0].text).tools[0];
+      expect(entry).toEqual(tool);
+    }
+    const schemaSearchMs = performance.now() - searchStart;
+    const args = { url: 'https://example.test/synthetic?q=1', tab_id: 'stub-tab' };
+    const directStart = performance.now();
+    const a = await clients[0].callTool({ name: 'browser_navigate', arguments: args });
+    const directCallMs = performance.now() - directStart;
+    const wrappedStart = performance.now();
+    const b = await clients[1].callTool({ name: 'tool_call', arguments: { name: 'browser_navigate', arguments: args } });
+    const wrappedCallMs = performance.now() - wrappedStart;
+    expect(a).toEqual(b); expect(a.isError).not.toBe(true);
+    expect(a.content).toEqual(browserResult.content);
+    expect(browserCalls).toHaveLength(2);
+    const params = browserCalls.map(call => (call as { params: unknown }).params);
+    expect(params[0]).toEqual(params[1]);
+    expect(params[0]).toEqual({ name: 'browser_navigate', arguments: { ...args, session_id: 'synthetic-session', agent_id: 'synthetic-agent' } });
+    expect(bridgeCalls.map(call => (call as { tool: string }).tool)).toEqual(['task_validate', 'task_validate']);
+    writeFileSync('/tmp/gateway-500-lazy-schema-smoke.json', JSON.stringify({
+      measuredAt: new Date().toISOString(), fixture: 'local synthetic browser and ticket bridge; no external provider/model calls',
+      directToolCount: direct.length, lazyToolCount: lazy.length, deferredToolCount: execution.length,
+      directSchemaBytes: Buffer.byteLength(JSON.stringify(direct)), lazySchemaBytes: Buffer.byteLength(JSON.stringify(lazy)),
+      readyMs, schemaSearchMs, directCallMs, wrappedCallMs,
+      note: 'Single local smoke timing, not a performance benchmark or model-level token savings measurement.',
+    }, null, 2));
+  } finally {
+    for (const client of clients) await client.close();
+    local.stop(true); rmSync(dir, { recursive: true, force: true });
+  }
+}, 15000);

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/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/receiver-server.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { parseSessionInfo } from './session-browser';
 /**
  * Telegram channel for Claude Gateway.
  *
@@ -877,8 +878,8 @@ const BOT_COMMANDS = [
   { 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: 'clear', description: 'Reset Claude Code context; keep chat history' },
+  { command: 'compact', description: 'Compact Claude Code context' },
   { 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' },
@@ -1169,8 +1170,8 @@ bot.command('help', async ctx => {
     `/sessions — list and switch between sessions\n` +
     `/new <name> — create a new session\n` +
     `/rename <name> — rename current session\n` +
-    `/clear — clear current session history\n` +
-    `/compact — summarise and compress session history\n` +
+    `/clear — reset context; keep chat history\n` +
+    `/compact — compact Claude Code context; keep chat history\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` +
@@ -1355,7 +1356,7 @@ bot.command('compact', async ctx => {
     .text('\u274c Cancel', 'compact:cancel')
 
   await ctx.reply(
-    '🧠 Compact session?\nThis will summarise old messages and keep only recent history.',
+    '🧠 Compact session?\nThis compacts Claude Code context. Your chat history stays unchanged.',
     { reply_markup: keyboard },
   )
 })
@@ -1514,24 +1515,37 @@ bot.command('voice', async ctx => {
   } 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
-  const access = loadAccess()
-  if (!access.allowFrom.includes(String(ctx.from!.id))) return
-  if (!CALLBACK_URL_BASE) return
-
-  try {
-    const res = await fetch(CALLBACK_URL_BASE + '/command', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ command: 'session_info', chat_id: String(ctx.chat.id) }),
+// Reuse the /tasks live-message lifecycle: serialize reads/replacement, edit only
+// changes, persist the last message across restart, and honor Telegram backoff.
+const SESSION_BROWSER_FILE = join(STATE_DIR, 'session-browser.json')
+let restoredSessionBrowsers: TaskBrowserMessage[] = []
+try { const saved = JSON.parse(readFileSync(SESSION_BROWSER_FILE, 'utf8')); if (Array.isArray(saved)) restoredSessionBrowsers = saved } catch {}
+const liveSessionBrowser = new LiveTaskBrowser({
+  read: async (chat) => {
+    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:'session_info',chat_id:chat}),
     })
-    const data = await res.json() as { success: boolean; text?: string }
-    await ctx.reply(data.text ?? '⚠️ Could not get session info.', { parse_mode: 'HTML' })
-  } catch {
-    await ctx.reply('⚠️ Could not connect to gateway.')
-  }
+    return parseSessionInfo(response.ok, await response.json())
+  },
+  render: result => ({text:(result as {sessionId:string;text:string}).text,reply_markup:{inline_keyboard:[]}}),
+  send: async (chat,menu) => (await bot.api.sendMessage(chat,menu.text,{parse_mode:'HTML'})).message_id,
+  edit: (chat,id,menu) => bot.api.editMessageText(chat,id,menu.text,{parse_mode:'HTML'}),
+  remove: (chat,id) => bot.api.deleteMessage(chat,id),
+  close: (chat,id) => bot.api.editMessageText(chat,id,'Session view closed.'),
+  allowed: (chat,user) => chat === user && loadAccess().allowFrom.includes(user),
+  persist: entries => {
+    mkdirSync(STATE_DIR,{recursive:true,mode:0o700})
+    const temp=SESSION_BROWSER_FILE+'.tmp'
+    writeFileSync(temp,JSON.stringify(entries),{mode:0o600});renameSync(temp,SESSION_BROWSER_FILE)
+  },
+},restoredSessionBrowsers)
+setInterval(()=>{void liveSessionBrowser.tick().catch(()=>{})},3000).unref()
+bot.command('session',async ctx=>{
+  if(ctx.chat?.type!=='private'||!isCallbackAuthorized(ctx))return
+  try{await liveSessionBrowser.open(String(ctx.chat.id),String(ctx.from!.id))}
+  catch{await ctx.reply('Could not load session info. Please try /session again.')}
 })
 
 // /sessions — list sessions with inline keyboard for switching/deleting
@@ -1583,18 +1597,18 @@ bot.command('sessions', async ctx => {
   }
 })
 
-// /clear — show Yes/No confirmation before clearing session history
+// /clear — confirm a fresh CLI context without deleting history
 bot.command('clear', async ctx => {
   if (ctx.chat?.type !== 'private') return
   const access = loadAccess()
   if (!access.allowFrom.includes(String(ctx.from!.id))) return
 
   await ctx.reply(
-    '🗑️ Clear session?\n\nThis will delete all message history. This cannot be undone.',
+    'Reset Claude Code context?\n\nChat history and attachments stay unchanged. Your next message starts a new context with the latest 50 messages.',
     {
       reply_markup: {
         inline_keyboard: [[
-          { text: '✅ Yes, clear it', callback_data: 'session_clear_confirm' },
+          { text: '✅ Reset context', callback_data: 'session_clear_confirm' },
           { text: '❌ Cancel', callback_data: 'session_clear_cancel' },
         ]],
       },
@@ -1880,10 +1894,10 @@ bot.on('callback_query:data', async ctx => {
           payload: { model: newModel },
         }),
       })
-      const result = (await res.json()) as { success?: boolean; error?: string; restarted?: boolean }
+      const result = (await res.json()) as { success?: boolean; error?: string; restarted?: boolean; appliesNextTurn?: boolean }
       if (result.success) {
         await ctx.answerCallbackQuery({ text: `✅ Model changed to ${newModel}` }).catch(() => {})
-        await ctx.editMessageText(`\u2705 Model changed to ${newModel}`).catch(() => {})
+        await ctx.editMessageText(`\u2705 Model changed to ${newModel}${result.appliesNextTurn ? "\nApplies to the next response; current work continues." : ""}`).catch(() => {})
       } else {
         await ctx.answerCallbackQuery({ text: result.error ?? 'Failed' }).catch(() => {})
       }
@@ -1920,7 +1934,7 @@ bot.on('callback_query:data', async ctx => {
           chat_id: String(ctx.callbackQuery.message?.chat.id),
         }),
       })
-      const result = (await res.json()) as { success?: boolean; error?: string; restarted?: boolean }
+      const result = (await res.json()) as { success?: boolean; error?: string; restarted?: boolean; appliesNextTurn?: boolean }
       if (result.success) {
         if (result.restarted === false) {
           // No active session — nothing to restart
@@ -2085,8 +2099,8 @@ bot.on('callback_query:data', async ctx => {
     }
     const chatId = String(ctx.callbackQuery.message?.chat.id)
     try {
-      await ctx.answerCallbackQuery({ text: 'Clearing...' }).catch(() => {})
-      await ctx.editMessageText('\u23f3 Clearing session...').catch(() => {})
+      await ctx.answerCallbackQuery({ text: 'Resetting context...' }).catch(() => {})
+      await ctx.editMessageText('\u23f3 Resetting context...').catch(() => {})
       const res = await fetch(CALLBACK_URL_BASE + '/command', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
@@ -2094,7 +2108,7 @@ bot.on('callback_query:data', async ctx => {
       })
       const result = (await res.json()) as { success?: boolean; error?: string }
       if (result.success) {
-        await ctx.reply('\uD83D\uDCA1 Session has been cleared').catch(() => {})
+        await ctx.reply('\uD83D\uDCA1 Claude Code context reset. Chat history is unchanged. The next message loads the latest 50 messages.').catch(() => {})
       } else {
         await ctx.reply(`\u274C Clear failed: ${result.error ?? 'Unknown error'}`).catch(() => {})
       }

package/mcp/tools/telegram/session-browser.ts

@@ -0,0 +1,10 @@
+/** A successful empty session is a status, not a transport failure. The empty
+ * ID binds its live message until a real session appears, when it is retired. */
+export function parseSessionInfo(ok: boolean, value: unknown): { sessionId: string; text: string } {
+  const result = value as { success?: unknown; sessionId?: unknown; text?: unknown } | null;
+  if (!ok || result?.success !== true || typeof result.text !== 'string' ||
+      !(result.sessionId === null || (typeof result.sessionId === 'string' && result.sessionId.length > 0))) {
+    throw new Error('Session info unavailable');
+  }
+  return { sessionId: result.sessionId ?? '', text: result.text };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xmaxma/claude-gateway",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Multi-agent gateway for Claude",
   "repository": {
     "type": "git",
@@ -52,6 +52,7 @@
     "chokidar": "^3.5.0",
     "cron-parser": "^5.5.0",
     "express": "^4.18.0",
+    "js-tiktoken": "^1.0.21",
     "js-yaml": "^4.1.0",
     "lru-cache": "^10.0.0",
     "node-cron": "^3.0.0",