@lydt/geogebra-studio 0.0.0-stage → 0.4.0-rc.2

package/src/server.ts

@@ -0,0 +1,168 @@
+import { EventEmitter } from 'events';
+import { readFileSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { inWorkspace } from './export/workspace';
+import { createServer, Server as HttpServer } from 'http';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import {
+  CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema,
+  ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema,
+  ErrorCode, McpError,
+} from '@modelcontextprotocol/sdk/types.js';
+import Ajv from 'ajv';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { toolRegistry } from './tools';
+import { McpServerConfig } from './types/mcp';
+import { instancePool } from './tools/geogebra-tools';
+import { optimizedInstancePool } from './utils/performance/instance-pool';
+
+const guidance = 'Use geogebra_build_artifact by default to produce a checked local HTML with a packed editable GGB and preview. geogebra_create_html is an unverified command-template alternative. ' +
+  'When saving files, pass workspace as the absolute user project directory; never use the installed plugin cache as the output directory. MCP roots are used when available. ' +
+  'For server-side work use geogebra_eval_commands, then native exports. ' +
+  'All TikZ exports use native PGF followed by Gikz; never return raw PGF as a final export. ' +
+  'Use geogebra_get_semantic_scene before semantic export; report unsupported objects and coordinate fallbacks. ' +
+  'Use geogebra_api_list_methods and geogebra_api_call for public Apps API methods not covered by focused tools. ' +
+  'All server-side tools share one construction. Do not interleave independent diagrams.';
+
+/** Official SDK owns framing, negotiation, notifications, and transport lifecycle. */
+export class McpServer extends EventEmitter {
+  private sdk?: Server;
+  private http?: HttpServer;
+  private connections = new Set<Server>();
+  private running = false;
+  private queue: Promise<unknown> = Promise.resolve();
+  constructor(private config: McpServerConfig) { super(); }
+
+  createProtocolServer(): Server {
+    const sdk = new Server({ name: this.config.name, version: this.config.version }, {
+      capabilities: { tools: {}, resources: {}, prompts: {} }, instructions: guidance,
+    });
+    const ajv = new Ajv({ strict: false, allErrors: true });
+    const core = new Set(['geogebra_build_artifact','server_info','geogebra_eval_commands','geogebra_clear_construction',
+      'geogebra_get_objects','geogebra_instance_status','geogebra_auto_zoom','geogebra_load_ggb',
+      'geogebra_export_ggb','geogebra_export_png','geogebra_export_svg','geogebra_export_pdf',
+      'geogebra_create_html','geogebra_export_html','geogebra_get_semantic_scene',
+      'geogebra_export_source','geogebra_export_tikz','geogebra_clean_tikz','geogebra_api_list_methods','geogebra_api_call','geogebra_api_get_callback_events']);
+    const tools = toolRegistry.getTools().filter(t => process.env['GEOGEBRA_TOOL_PROFILE'] !== 'core' || core.has(t.name))
+      .map(tool=>tool.inputSchema.properties['filename']?{...tool,inputSchema:{...tool.inputSchema,properties:{...tool.inputSchema.properties,workspace:{type:'string',description:'Absolute user workspace directory for saved files. Pass this when the client does not provide MCP roots; never use the plugin cache directory.'}}}}:tool)
+      .sort((a,b)=>a.name.localeCompare(b.name));
+    const validators = new Map(tools.map(t => [t.name, ajv.compile(t.inputSchema)]));
+    sdk.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+    sdk.setRequestHandler(CallToolRequestSchema, async request => {
+      const { name, arguments: args = {} } = request.params;
+      const validate = validators.get(name);
+      if (!validate) throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
+      if (!validate(args)) throw new McpError(ErrorCode.InvalidParams, ajv.errorsText(validate.errors));
+      // Queue the entire operation, including export, to avoid cross-request mutation races.
+      const operation = this.queue.then(async () => {
+        try {
+          let workspace=args['workspace'];
+          if(args['filename']!==undefined&&!workspace&&sdk.getClientCapabilities()?.roots){
+            const roots=await sdk.listRoots({}, {timeout:5000});
+            const folders=roots.roots.filter(root=>root.uri.startsWith('file:')).map(root=>fileURLToPath(root.uri));
+            workspace=folders.length===1?folders[0]:folders.find(root=>typeof args['filename']==='string'&&path.isAbsolute(args['filename'])&&args['filename'].startsWith(root+path.sep));
+          }
+          if(args['filename']!==undefined&&!workspace&&process.env['GEOGEBRA_PLUGIN_RUNTIME']==='1'&&!process.env['VSCODE_WORKSPACE_FOLDER'])
+            throw new Error('Provide workspace as the absolute user project directory. The plugin cache is not an output workspace.');
+          const result = await inWorkspace(workspace,()=>toolRegistry.executeTool(name, args));
+          if (!result.structuredContent && result.content.length === 1 && result.content[0]?.text) {
+            try {
+              const value: unknown = JSON.parse(result.content[0].text);
+              if (value && typeof value === 'object' && !Array.isArray(value)) {
+                return { ...result, structuredContent: value as Record<string, unknown> };
+              }
+            } catch { /* Existing plain text tools remain valid. */ }
+          }
+          return result;
+        } catch (error) {
+          return { content: [{ type: 'text' as const, text: error instanceof Error ? error.message : String(error) }], isError: true };
+        }
+      });
+      this.queue = operation.catch(() => undefined);
+      return operation;
+    });
+    sdk.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: [{
+      uri: 'geogebra://guide', name: 'GeoGebra construction and export guide', mimeType: 'text/plain',
+    }, { uri: 'ui://geogebra/preview.html', name: 'GeoGebra preview', mimeType: 'text/html;profile=mcp-app' }] }));
+    sdk.setRequestHandler(ReadResourceRequestSchema, async request => {
+      if (request.params.uri === 'ui://geogebra/preview.html') return { contents: [{
+        uri: request.params.uri, mimeType: 'text/html;profile=mcp-app',
+        text: readFileSync(path.join(__dirname,'widget.html'),'utf8'),
+        _meta: { ui: { csp: {
+          resourceDomains: ['https://www.geogebra.org','https://geogebra.org','https://cdn.geogebra.org'],
+          connectDomains: ['https://www.geogebra.org','https://geogebra.org','https://cdn.geogebra.org'],
+        } } },
+      }] };
+      if (request.params.uri !== 'geogebra://guide') throw new McpError(ErrorCode.InvalidParams, 'Unknown resource');
+      return { contents: [{ uri: 'geogebra://guide', mimeType: 'text/plain', text: guidance }] };
+    });
+    sdk.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [{
+      name: 'construct-geometry', description: 'Build an editable, print-style GeoGebra construction',
+      arguments: [{ name: 'problem', description: 'Geometry definitions and target exports', required: true }],
+    }] }));
+    sdk.setRequestHandler(GetPromptRequestSchema, async request => {
+      if (request.params.name !== 'construct-geometry' || !request.params.arguments?.['problem']) {
+        throw new McpError(ErrorCode.InvalidParams, 'construct-geometry requires problem');
+      }
+      return { messages: [{ role: 'user' as const, content: { type: 'text' as const,
+        text: `${guidance}\n\n${request.params.arguments['problem']}` } }] };
+    });
+    return sdk;
+  }
+
+  async start(): Promise<void> {
+    if (this.running) return;
+    this.sdk = this.createProtocolServer();
+    this.sdk.onclose = () => { if (this.running) void this.stop(); };
+    await this.sdk.connect(new StdioServerTransport());
+    this.running = true;
+    this.emit('started');
+  }
+
+  /** Loopback-only, single-user HTTP. Deploy behind HTTPS + authentication for remote use. */
+  async startHttp(port: number): Promise<void> {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Invalid HTTP port');
+    this.http = createServer(async (req, res) => {
+      if (req.url !== '/mcp') { res.writeHead(404).end(); return; }
+      if (req.headers.origin && ![`http://localhost:${port}`, `http://127.0.0.1:${port}`].includes(req.headers.origin)) {
+        res.writeHead(403).end('Origin forbidden'); return;
+      }
+      const host = req.headers.host;
+      if (!host || ![`localhost:${port}`, `127.0.0.1:${port}`].includes(host)) {
+        res.writeHead(403).end('Host forbidden'); return;
+      }
+      const sdk = this.createProtocolServer();
+      const transport = new StreamableHTTPServerTransport({ enableJsonResponse: true });
+      this.connections.add(sdk);
+      res.on('close', () => { void sdk.close(); this.connections.delete(sdk); });
+      try {
+        await sdk.connect(transport as Transport);
+        await transport.handleRequest(req, res);
+      } catch { if (!res.headersSent) res.writeHead(500).end('MCP request failed'); }
+    });
+    await new Promise<void>((resolve, reject) => {
+      this.http!.once('error', reject);
+      this.http!.listen(port, '127.0.0.1', resolve);
+    });
+    this.running = true;
+    this.emit('started');
+  }
+
+  async stop(): Promise<void> {
+    this.running = false;
+    await this.queue;
+    await this.sdk?.close();
+    await Promise.all([...this.connections].map(s => s.close()));
+    if (this.http) await new Promise<void>((resolve, reject) => this.http!.close(e => e ? reject(e) : resolve()));
+    await instancePool.cleanup();
+    await optimizedInstancePool.cleanup();
+    this.running = false;
+    this.emit('stopped');
+  }
+  getStatus() { return { ...this.config, isRunning: this.running, toolCount: toolRegistry.getToolCount(), uptime: this.running ? process.uptime() : 0 }; }
+  getConfig() { return { ...this.config }; }
+  isServerRunning() { return this.running; }
+}

package/src/studio/artifact.ts

@@ -0,0 +1,50 @@
+declare const window: any;
+import { readFile, unlink } from 'fs/promises';
+import { GeoGebraInstance } from '../utils/geogebra-instance';
+import { constructionHtml, HtmlOptions } from '../export/html';
+import { saveFile, saveText } from '../export/files';
+/** Isolated native execution → packed GGB → reopen final viewer → save, never a shared pool reset. */
+export async function buildArtifact(options:HtmlOptions & {filename:string}) {
+  if(!/\.html$/i.test(options.filename))throw new Error('filename must end in .html');
+  if(!options.ggbBase64&&!options.commands?.length)throw new Error('Provide nonempty commands or a packed ggbBase64');
+  const engine=new GeoGebraInstance({width:options.width||1000,height:options.height||800});
+  let filename:string|undefined;
+  let previewFilename:string|undefined;
+  let committed=false;
+  try{
+    await engine.initialize();
+    await engine.renderHtml(constructionHtml(options));
+    const checks=await engine.debugEvaluate<{objects:number;undefinedVisibleObjects:string[]}>(()=>{
+      const api=(window as any).ggbApplet,names=api.getAllObjectNames();
+      return {objects:names.length,undefinedVisibleObjects:names.filter((name:string)=>api.getVisible(name)&&!api.isDefined(name))};
+    });
+    if(checks.undefinedVisibleObjects.length)throw new Error('Undefined visible objects: '+checks.undefinedVisibleObjects.join(', '));
+    const ggbBase64=await engine.exportGGB();
+    const html=constructionHtml({...options,commands:[],ggbBase64});
+    filename=await saveText(options.filename,html);
+    if(!filename)throw new Error('Unable to save the final HTML artifact');
+    // Reopen the exact bytes written to disk so the preview and verification describe
+    // the delivered file, including its packed GGB payload.
+    await engine.renderHtml(await readFile(filename,'utf8'));
+    const layout=await engine.debugEvaluate<{ready:boolean;error:string|null;equalAxes:boolean;viewWidth:number;viewHeight:number}>(()=>{
+      const api=(window as any).ggbApplet,view=JSON.parse(api.getViewProperties(1));
+      return {ready:(window as any).ggbReady===true,error:(window as any).ggbError||null,
+        equalAxes:Math.abs(view.invXscale/view.invYscale-1)<1e-6,viewWidth:view.width,viewHeight:view.height};
+    });
+    if(!layout.ready||layout.error||!layout.equalAxes||layout.viewWidth<=0||layout.viewHeight<=0)
+      throw new Error('Final HTML viewer verification failed: '+JSON.stringify(layout));
+    const packedObjects=await engine.getAllObjectNames();
+    if(packedObjects.length!==checks.objects)throw new Error('Packed GGB round trip changed object count');
+    const preview=await engine.capturePreview();
+    previewFilename=await saveFile(options.filename.replace(/\.html$/i,'.preview.png'),preview);
+    committed=true;
+    const data={success:true,format:'html',filename,previewFilename,html,engineVerified:true,packedGgbVerified:true,
+      layoutChecks:{loaded:true,equalAxes:layout.equalAxes,viewWidth:layout.viewWidth,viewHeight:layout.viewHeight},renderVerified:true,requiresNetwork:true,objectCount:checks.objects,
+      note:'Native execution, saved HTML reopen, packed GGB, equal axes and preview capture passed. Inspect the attached preview for visual quality.'};
+    return {content:[{type:'text' as const,text:JSON.stringify(data)},{type:'image' as const,mimeType:'image/png',data:Buffer.from(preview).toString('base64')}],structuredContent:data};
+  }finally{
+    if(!committed&&previewFilename)await unlink(previewFilename);
+    if(!committed&&filename)await unlink(filename);
+    await engine.cleanup();
+  }
+}

package/src/studio/browser.ts

@@ -0,0 +1,38 @@
+import path from 'path';
+import os from 'os';
+import { existsSync, readFileSync } from 'fs';
+import { mkdir, writeFile } from 'fs/promises';
+import puppeteer from 'puppeteer-core';
+const {PUPPETEER_REVISIONS}=require('puppeteer-core') as {PUPPETEER_REVISIONS:{chrome:string}};
+import { Browser, computeExecutablePath, install } from '@puppeteer/browsers';
+export const browserCache = () => path.join(process.env['GEOGEBRA_STUDIO_HOME'] || path.join(os.homedir(),'.cache','geogebra-studio'),'browsers');
+export const managedBrowserPath = () => computeExecutablePath({cacheDir:browserCache(),browser:Browser.CHROME,buildId:PUPPETEER_REVISIONS.chrome});
+export function browserCandidates(): string[] {
+  const explicit=process.env['PUPPETEER_EXECUTABLE_PATH'];
+  if(explicit)return [explicit];
+  return [
+    ...(process.platform==='darwin'?['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',path.join(os.homedir(),'Applications/Google Chrome.app/Contents/MacOS/Google Chrome')]:[]),
+    ...(process.platform==='win32'?[process.env['PROGRAMFILES'],process.env['PROGRAMFILES(X86)'],process.env['LOCALAPPDATA']].filter((v):v is string=>!!v).map(v=>path.join(v,'Google','Chrome','Application','chrome.exe')):[]),
+    ...(process.platform==='linux'?['/usr/bin/google-chrome','/usr/bin/google-chrome-stable','/usr/bin/chromium','/usr/bin/chromium-browser']:[]),
+    managedBrowserPath(),
+  ].filter((value,index,all)=>all.indexOf(value)===index);
+}
+/** Runtime lookup is cheap; installation/doctor additionally probes launch compatibility. */
+export function resolveBrowser(): string {
+  if(!process.env['PUPPETEER_EXECUTABLE_PATH']){try{const selected=readFileSync(path.join(browserCache(),'selected.txt'),'utf8').trim();if(existsSync(selected))return selected;}catch{/* No prepared runtime yet. */}}
+  const executable=browserCandidates().find(file=>existsSync(file));
+  if(!executable)throw new Error('Chrome is unavailable. Run: npx @lydt/geogebra-studio browser install');
+  return executable;
+}
+async function rememberBrowser(file:string):Promise<string>{await mkdir(browserCache(),{recursive:true});await writeFile(path.join(browserCache(),'selected.txt'),file,'utf8');return file;}
+export async function prepareBrowser(download=false): Promise<string> {
+  const failures:string[]=[];
+  for(const file of browserCandidates().filter(file=>existsSync(file))){
+    try{const browser=await puppeteer.launch({executablePath:file,headless:true,timeout:15000});await browser.close();return rememberBrowser(file);}
+    catch(error){failures.push(`${file}: ${error instanceof Error?error.message:String(error)}`);}
+  }
+  if(!download)throw new Error('No usable Chrome. Run: npx @lydt/geogebra-studio browser install. '+failures.join('; '));
+  const installed=await install({browser:Browser.CHROME,buildId:PUPPETEER_REVISIONS.chrome,cacheDir:browserCache()});
+  const browser=await puppeteer.launch({executablePath:installed.executablePath,headless:true,timeout:15000});await browser.close();
+  return rememberBrowser(installed.executablePath);
+}

package/src/studio/install.ts

@@ -0,0 +1,43 @@
+import path from 'path';
+import os from 'os';
+import { mkdir, writeFile, readFile, cp, access } from 'fs/promises';
+import { spawn } from 'child_process';
+import { prepareBrowser } from './browser';
+export async function run(command:string,args:string[],cwd?:string):Promise<void>{
+  await new Promise<void>((resolve,reject)=>{
+    const child=spawn(command,args,{stdio:'inherit',shell:false,...(cwd?{cwd}: {})});
+    child.once('error',reject);child.once('close',code=>code===0?resolve():reject(new Error(`${command} exited with ${code}`)));
+  });
+}
+/** A persistent catalog uses an npm source, never the temporary npx package directory. */
+export async function installPlugin(local=false):Promise<void>{
+  const metadata=JSON.parse(await readFile(path.join(__dirname,'../../package.json'),'utf8'));
+  const home=process.env['CODEX_HOME']||path.join(os.homedir(),'.codex');
+  const root=path.join(home,'geogebra-studio','marketplace');
+  await mkdir(path.join(root,'.agents','plugins'),{recursive:true});
+  let source:Record<string,string>={source:'npm',package:metadata.name,version:metadata.version};
+  if(local){
+    // Explicit authoring mode copies release files to a stable location and installs runtime deps.
+    const target=path.join(root,'plugin');
+    try{await access(path.join(target,'package.json'));throw new Error(`Local package already exists: ${target}. Use a fresh CODEX_HOME for a clean test.`);}catch(error){if((error as NodeJS.ErrnoException).code!=='ENOENT')throw error;}
+    await mkdir(target,{recursive:true});
+    const packageRoot=path.join(__dirname,'../..');
+    for(const entry of ['dist','runtime','gikz','skills','docs','plugin.json','mcp.json','.codex-plugin','.mcp.json','package.json','LICENSE','LICENSE-MIT','THIRD_PARTY_NOTICES.md'])await cp(path.join(packageRoot,entry),path.join(target,entry),{recursive:true});
+    const localPackagePath=path.join(target,'package.json');
+    const localPackage=JSON.parse(await readFile(localPackagePath,'utf8'));
+    delete localPackage.devDependencies;
+    await writeFile(localPackagePath,JSON.stringify(localPackage,null,2)+'\n');
+    await run(process.platform==='win32'?'npm.cmd':'npm',['install','--omit=dev','--ignore-scripts','--no-audit','--no-fund'],target);
+    // Authoring mode tests the CLI installed at this stable path. Keep its command
+    // portable and resolve the entry point from the plugin root.
+    const localServer={command:'node',args:['dist/cli.js','mcp'],cwd:'./',env:{GEOGEBRA_TOOL_PROFILE:'core',GEOGEBRA_PLUGIN_RUNTIME:'1'}};
+    await writeFile(path.join(target,'mcp.json'),JSON.stringify({$schema:'https://agent-plugins.org/schemas/1.0.0/mcp.schema.json',mcpServers:{geogebra:{type:'stdio',...localServer}}},null,2)+'\n');
+    await writeFile(path.join(target,'.mcp.json'),JSON.stringify({mcpServers:{geogebra:localServer}},null,2)+'\n');
+    source={source:'local',path:'./plugin'};
+  }
+  await writeFile(path.join(root,'.agents/plugins/marketplace.json'),JSON.stringify({name:'geogebra-studio',interface:{displayName:'GeoGebra Studio'},plugins:[{name:'geogebra-studio',source,policy:{installation:'AVAILABLE',authentication:'ON_INSTALL'},category:'Education'}]},null,2)+'\n');
+  await run('codex',['plugin','marketplace','add',root]);
+  await run('codex',['plugin','add','geogebra-studio@geogebra-studio']);
+  const executable=await prepareBrowser(true);
+  console.log(`GeoGebra Studio ${metadata.version} installed. Browser: ${executable}\nStart a new Codex session and invoke @geogebra-studio. Existing geogebra-geometry installations were not removed.`);
+}

package/src/tools/apps-api-tools.ts

@@ -0,0 +1,96 @@
+import { ToolDefinition } from '../types/mcp';
+import { cleanWithGikz } from '../export/gikz';
+import { instancePool } from './geogebra-tools';
+
+const result = (value: Record<string, unknown>) => ({
+  content: [{ type: 'text' as const, text: JSON.stringify(value) }], structuredContent: value,
+});
+
+/** A schema-checked bridge to the public methods exposed by the loaded GeoGebra Apps API. */
+export const appsApiTools: ToolDefinition[] = [
+  {
+    tool: {
+      name: 'geogebra_api_list_methods',
+      description: 'List callable methods exposed by the active GeoGebra Apps API. Availability depends on the loaded GeoGebra app/version.',
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    handler: async () => {
+      try {
+        const methods = await (await instancePool.getDefaultInstance()).listAppsApiMethods();
+        return result({ success: true, methods, count: methods.length });
+      } catch (error) {
+        return { ...result({ success: false, error: error instanceof Error ? error.message : String(error) }), isError: true };
+      }
+    },
+  },
+  {
+    tool: {
+      name: 'geogebra_api_call',
+      description: 'Call a public GeoGebra Apps API method by name with JSON arguments. Use geogebra_api_list_methods first. For one-shot callback exports set waitForCallbackIndex (0 for getBase64/exportSVG/getScreenshotBase64; 1 for exportPDF). For persistent listener functions put {"$ggbCallbackId":"my-id"} at that argument, then poll geogebra_api_get_callback_events; reuse the same marker to unregister. exportPGF always returns Gikz-cleaned standalone TikZ through this bridge. Destructive methods require allowDestructive=true.',
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+      inputSchema: {
+        type: 'object',
+        properties: {
+          method: { type: 'string', minLength: 1, maxLength: 100 },
+          args: { type: 'array', maxItems: 20, items: {} },
+          waitForCallbackIndex: { type: 'integer', minimum: 0, maximum: 20 },
+          callbackTimeoutMs: { type: 'integer', minimum: 100, maximum: 60000 },
+          allowDestructive: { type: 'boolean', description: 'Required for methods that clear, replace, open, or remove a construction/applet.' },
+        },
+        required: ['method'], additionalProperties: false,
+      },
+    },
+    handler: async params => {
+      try {
+        const method = params['method'] as string;
+        if (method === 'exportPGF') {
+          const source = await (await instancePool.getDefaultInstance()).exportNativeTikZ();
+          const value = await cleanWithGikz(source, {standalone:true});
+          return result({success:true,method,value,backend:'native-pgf+gikz',cleaned:true,semantics:'visual-snapshot'});
+        }
+        const dangerous = new Set(['newConstruction','reset','openFile','setXML','evalXML','setBase64','remove']);
+        if (dangerous.has(method) && params['allowDestructive'] !== true) {
+          throw new Error(`${method} can replace or clear construction data; set allowDestructive=true to proceed`);
+        }
+        const args = (params['args'] as unknown[] | undefined) ?? [];
+        const callbacks: Array<{ argumentIndex: number; id: string }> = [];
+        for (let i = 0; i < args.length; i++) {
+          const arg = args[i];
+          if (arg && typeof arg === 'object' && !Array.isArray(arg) && typeof (arg as Record<string, unknown>)['$ggbCallbackId'] === 'string') {
+            callbacks.push({ argumentIndex: i, id: (arg as Record<string, unknown>)['$ggbCallbackId'] as string });
+            args[i] = null;
+          }
+        }
+        const value = await (await instancePool.getDefaultInstance()).callAppsApi(
+          method,
+          args,
+          {
+            ...(typeof params['waitForCallbackIndex'] === 'number' ? { waitForCallbackIndex: params['waitForCallbackIndex'] } : {}),
+            ...(typeof params['callbackTimeoutMs'] === 'number' ? { callbackTimeoutMs: params['callbackTimeoutMs'] } : {}),
+            ...(callbacks.length ? { callbacks } : {}),
+          },
+        );
+        return result({ success: true, method, value: value === undefined ? null : value });
+      } catch (error) {
+        return { ...result({ success: false, error: error instanceof Error ? error.message : String(error) }), isError: true };
+      }
+    },
+  },
+  {
+    tool: {
+      name: 'geogebra_api_get_callback_events',
+      description: 'Read events captured from persistent GeoGebra Apps API listeners registered through geogebra_api_call. Set clear=false to read without clearing the queue.',
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+      inputSchema: { type: 'object', properties: { callbackId: { type: 'string', minLength: 1, maxLength: 80 }, clear: { type: 'boolean', default: true } }, required: ['callbackId'], additionalProperties: false },
+    },
+    handler: async params => {
+      try {
+        const events = await (await instancePool.getDefaultInstance()).readAppsApiCallbackEvents(params['callbackId'] as string, params['clear'] !== false);
+        return result({ success: true, callbackId: params['callbackId'], events });
+      } catch (error) {
+        return { ...result({ success: false, error: error instanceof Error ? error.message : String(error) }), isError: true };
+      }
+    },
+  },
+];