bloby-bot 0.33.2 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bloby-bot",
-  "version": "0.33.2",
+  "version": "0.35.0",
   "releaseNotes": [
     "1. # voice note (PTT bubble)",
     "2. # audio file + caption",

package/supervisor/agent-api.ts

@@ -1,12 +1,15 @@
 /**
- * Agent API — exposes the Claude Agent SDK to workspace code.
+ * Agent API — exposes the active agent harness to workspace code.
  *
  * Single endpoint: POST /api/agent/query
  *
  * If `systemPromptPath` is provided → read it from workspace, use as systemPrompt.
- * If omitted → use the `claude_code` preset (built-in Claude Code tools + prompt).
+ * If omitted → harness picks its own default coding-agent prompt
+ *   (Claude → `claude_code` preset; Codex → its built-in agent prompt).
  *
- * Supports session persistence via `sessionId` (pass the one returned from a previous call).
+ * Supports session persistence via `sessionId` (pass the one returned from a
+ * previous call). Provider-specific: Claude uses SDK session_id, Codex uses
+ * threadId — but the value is opaque to the caller.
  *
  * Auth: per-session secret injected into the workspace backend as BLOBY_AGENT_SECRET.
  * Safety: localhost-only, path traversal prevention, concurrency + rate limits, timeouts.
@@ -14,10 +17,8 @@
 
 import fs from 'fs';
 import path from 'path';
-import { query, type SDKMessage } from '@anthropic-ai/claude-agent-sdk';
 import { WORKSPACE_DIR } from '../shared/paths.js';
-import { log } from '../shared/logger.js';
-import { getClaudeAccessToken } from '../worker/claude-auth.js';
+import { runAgentQuery } from './bloby-agent.js';
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -25,7 +26,7 @@ export interface AgentQueryRequest {
   message: string;
   systemPromptPath?: string;    // relative to workspace, e.g. "skills/my-skill/prompt.txt"
   sessionId?: string;           // resume a previous session
-  maxTurns?: number;            // default 25, max 50
+  maxTurns?: number;            // default 25, max 50 (Claude only)
   timeout?: number;             // ms, default 120_000, max 300_000
 }
 
@@ -48,14 +49,11 @@ let activeQueries = 0;
 const requestTimestamps: number[] = [];
 
 function checkRateLimit(): string | null {
-  // Concurrency check
   if (activeQueries >= MAX_CONCURRENT) {
     return `Too many concurrent queries (max ${MAX_CONCURRENT}). Try again shortly.`;
   }
 
-  // Rate limit check
   const now = Date.now();
-  // Prune old timestamps
   while (requestTimestamps.length && requestTimestamps[0]! < now - RATE_LIMIT_WINDOW) {
     requestTimestamps.shift();
   }
@@ -68,11 +66,10 @@ function checkRateLimit(): string | null {
 
 // ── Path Validation ────────────────────────────────────────────────────────
 
-function resolveSystemPromptPath(relPath: string): { path: string } | { error: string } {
+function resolveSystemPromptPath(relPath: string): { content: string } | { error: string } {
   const resolved = path.resolve(WORKSPACE_DIR, relPath);
   const workspaceBoundary = WORKSPACE_DIR + path.sep;
 
-  // Must be inside workspace (not parent traversal)
   if (!resolved.startsWith(workspaceBoundary) && resolved !== WORKSPACE_DIR) {
     return { error: 'System prompt path must be within the workspace directory.' };
   }
@@ -81,144 +78,45 @@ function resolveSystemPromptPath(relPath: string): { path: string } | { error: s
     return { error: `System prompt file not found: ${relPath}` };
   }
 
-  return { path: resolved };
+  try {
+    const content = fs.readFileSync(resolved, 'utf-8').trim();
+    if (!content) return { error: 'System prompt file is empty.' };
+    return { content };
+  } catch (err: any) {
+    return { error: `Failed to read system prompt: ${err.message}` };
+  }
 }
 
 // ── Main Query Handler ─────────────────────────────────────────────────────
 
 export async function handleAgentQuery(req: AgentQueryRequest): Promise<AgentQueryResponse> {
-  // ── Validate inputs ──
   if (!req.message || typeof req.message !== 'string') {
     return { ok: false, error: 'Missing or invalid "message" field.' };
   }
 
-  const maxTurns = Math.min(Math.max(req.maxTurns || 25, 1), 50);
-  const timeout = Math.min(Math.max(req.timeout || 120_000, 5_000), 300_000);
-
-  // ── Rate limit ──
   const rateLimitError = checkRateLimit();
-  if (rateLimitError) {
-    return { ok: false, error: rateLimitError };
-  }
-
-  // ── Resolve system prompt ──
-  let systemPrompt: string | { type: 'preset'; preset: 'claude_code' };
+  if (rateLimitError) return { ok: false, error: rateLimitError };
 
+  let systemPrompt: string | undefined;
   if (req.systemPromptPath) {
     const result = resolveSystemPromptPath(req.systemPromptPath);
-    if ('error' in result) {
-      return { ok: false, error: result.error };
-    }
-    try {
-      const content = fs.readFileSync(result.path, 'utf-8').trim();
-      if (!content) {
-        return { ok: false, error: 'System prompt file is empty.' };
-      }
-      systemPrompt = content;
-    } catch (err: any) {
-      return { ok: false, error: `Failed to read system prompt: ${err.message}` };
-    }
-  } else {
-    systemPrompt = { type: 'preset', preset: 'claude_code' };
+    if ('error' in result) return { ok: false, error: result.error };
+    systemPrompt = result.content;
   }
 
-  // ── OAuth token ──
-  const oauthToken = await getClaudeAccessToken();
-  if (!oauthToken) {
-    return { ok: false, error: 'Claude OAuth token not found. Please authenticate via the dashboard.' };
-  }
-
-  // ── Execute query ──
   activeQueries++;
   requestTimestamps.push(Date.now());
 
-  const abortController = new AbortController();
-  const timeoutHandle = setTimeout(() => abortController.abort(), timeout);
-
-  let fullText = '';
-  const usedTools = new Set<string>();
-  let sessionId: string | undefined;
-  let stderrBuf = '';
-
   try {
-    log.info(`[agent-api] Query: msg="${req.message.slice(0, 80)}..." maxTurns=${maxTurns} timeout=${timeout}ms resume=${req.sessionId || 'none'}`);
-
-    const claudeQuery = query({
-      prompt: req.message,
-      options: {
-        cwd: WORKSPACE_DIR,
-        permissionMode: 'bypassPermissions',
-        allowDangerouslySkipPermissions: true,
-        maxTurns,
-        abortController,
-        systemPrompt: systemPrompt as any,
-        ...(req.sessionId ? { resume: req.sessionId } : {}),
-        stderr: (chunk: string) => { stderrBuf += chunk; },
-        env: {
-          ...process.env as Record<string, string>,
-          CLAUDE_CODE_OAUTH_TOKEN: oauthToken,
-          CLAUDE_CODE_BUBBLEWRAP: '1',
-        },
-      },
+    const result = await runAgentQuery({
+      message: req.message,
+      systemPrompt,
+      sessionId: req.sessionId,
+      maxTurns: req.maxTurns,
+      timeout: req.timeout,
     });
-
-    for await (const msg of claudeQuery) {
-      if (abortController.signal.aborted) break;
-
-      switch (msg.type) {
-        case 'assistant': {
-          const assistantMsg = (msg as any).message;
-          if (!assistantMsg?.content) break;
-          for (const block of assistantMsg.content) {
-            if (block.type === 'text' && block.text) {
-              if (fullText && !fullText.endsWith('\n')) fullText += '\n\n';
-              fullText += block.text;
-            } else if (block.type === 'tool_use') {
-              usedTools.add(block.name);
-            }
-          }
-          break;
-        }
-        case 'result': {
-          // Extract session_id from result for persistence
-          sessionId = (msg as any).session_id;
-
-          if (!fullText && (msg as any).subtype?.startsWith('error')) {
-            const errors = (msg as any).errors?.join('; ') || 'Agent query failed';
-            return {
-              ok: false,
-              error: errors,
-              sessionId,
-              toolsUsed: Array.from(usedTools),
-            };
-          }
-          break;
-        }
-      }
-    }
-
-    const FILE_TOOLS = ['Write', 'Edit'];
-    const usedFileTools = FILE_TOOLS.some((t) => usedTools.has(t));
-
-    log.info(`[agent-api] Done: ${fullText.length} chars, tools=[${Array.from(usedTools).join(',')}], session=${sessionId || 'unknown'}`);
-
-    return {
-      ok: true,
-      response: fullText,
-      sessionId,
-      toolsUsed: Array.from(usedTools),
-      usedFileTools,
-    };
-  } catch (err: any) {
-    if (abortController.signal.aborted) {
-      return { ok: false, error: 'Query timed out.', sessionId };
-    }
-    const detail = stderrBuf.trim();
-    const errMsg = detail ? `${err.message}\n\n${detail}` : err.message;
-    log.warn(`[agent-api] Error: ${errMsg}`);
-    return { ok: false, error: errMsg, sessionId };
+    return result;
   } finally {
-    clearTimeout(timeoutHandle);
     activeQueries--;
   }
 }

package/supervisor/bloby-agent.ts

@@ -17,11 +17,11 @@
 
 import * as claude from './harnesses/claude.js';
 import * as codex from './harnesses/codex.js';
-import type { Harness, OnAgentMessage, RecentMessage, AgentAttachment } from './harnesses/types.js';
+import type { Harness, OnAgentMessage, RecentMessage, AgentAttachment, AgentQueryRequest, AgentQueryResult } from './harnesses/types.js';
 import type { SavedFile } from './file-saver.js';
 import { loadConfig } from '../shared/config.js';
 
-export type { RecentMessage, AgentAttachment };
+export type { RecentMessage, AgentAttachment, AgentQueryRequest, AgentQueryResult };
 
 const HARNESSES: Record<string, Harness> = {
   anthropic: claude,
@@ -123,3 +123,9 @@ export function startBlobyAgentQuery(
 export function stopBlobyAgentQuery(conversationId: string): void {
   for (const h of Object.values(HARNESSES)) h.stopBlobyAgentQuery(conversationId);
 }
+
+/* ── Workspace agent endpoint ──────────────────────────────────────────── */
+
+export function runAgentQuery(req: AgentQueryRequest): Promise<AgentQueryResult> {
+  return activeHarness().runAgentQuery(req);
+}

package/supervisor/harnesses/claude.ts

@@ -23,7 +23,7 @@ import { preWarm, claimWarmup, discardWarmup } from '../cli-warmup.js';
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
-import type { RecentMessage, AgentAttachment } from './types.js';
+import type { RecentMessage, AgentAttachment, AgentQueryRequest, AgentQueryResult } from './types.js';
 export type { RecentMessage, AgentAttachment };
 
 // ── Async Queue ────────────────────────────────────────────────────────────
@@ -682,3 +682,95 @@ export function stopBlobyAgentQuery(conversationId: string): void {
     activeQueries.delete(conversationId);
   }
 }
+
+// ── Workspace agent endpoint (POST /api/agent/query) ──────────────────────
+
+export async function runAgentQuery(req: AgentQueryRequest): Promise<AgentQueryResult> {
+  const oauthToken = await getClaudeAccessToken();
+  if (!oauthToken) {
+    return { ok: false, error: 'Claude OAuth token not found. Please authenticate via the dashboard.' };
+  }
+
+  const maxTurns = Math.min(Math.max(req.maxTurns || 25, 1), 50);
+  const timeout = Math.min(Math.max(req.timeout || 120_000, 5_000), 300_000);
+
+  // Empty/missing systemPrompt → fall back to Claude's built-in `claude_code`
+  // preset (its native coding-agent prompt + tools).
+  const systemPrompt: string | { type: 'preset'; preset: 'claude_code' } =
+    req.systemPrompt ? req.systemPrompt : { type: 'preset', preset: 'claude_code' };
+
+  const abortController = new AbortController();
+  const timeoutHandle = setTimeout(() => abortController.abort(), timeout);
+
+  let fullText = '';
+  const usedTools = new Set<string>();
+  let sessionId: string | undefined;
+  let stderrBuf = '';
+
+  try {
+    log.info(`[claude/agent-api] Query: msg="${req.message.slice(0, 80)}..." maxTurns=${maxTurns} timeout=${timeout}ms resume=${req.sessionId || 'none'}`);
+
+    const claudeQuery = query({
+      prompt: req.message,
+      options: {
+        cwd: WORKSPACE_DIR,
+        permissionMode: 'bypassPermissions',
+        allowDangerouslySkipPermissions: true,
+        maxTurns,
+        abortController,
+        systemPrompt: systemPrompt as any,
+        ...(req.sessionId ? { resume: req.sessionId } : {}),
+        stderr: (chunk: string) => { stderrBuf += chunk; },
+        env: {
+          ...process.env as Record<string, string>,
+          CLAUDE_CODE_OAUTH_TOKEN: oauthToken,
+          CLAUDE_CODE_BUBBLEWRAP: '1',
+        },
+      },
+    });
+
+    for await (const msg of claudeQuery) {
+      if (abortController.signal.aborted) break;
+
+      switch (msg.type) {
+        case 'assistant': {
+          const assistantMsg = (msg as any).message;
+          if (!assistantMsg?.content) break;
+          for (const block of assistantMsg.content) {
+            if (block.type === 'text' && block.text) {
+              if (fullText && !fullText.endsWith('\n')) fullText += '\n\n';
+              fullText += block.text;
+            } else if (block.type === 'tool_use') {
+              usedTools.add(block.name);
+            }
+          }
+          break;
+        }
+        case 'result': {
+          sessionId = (msg as any).session_id;
+          if (!fullText && (msg as any).subtype?.startsWith('error')) {
+            return {
+              ok: false,
+              error: (msg as any).errors?.join('; ') || 'Agent query failed',
+              sessionId,
+              toolsUsed: Array.from(usedTools),
+            };
+          }
+          break;
+        }
+      }
+    }
+
+    const usedFileTools = ['Write', 'Edit'].some((t) => usedTools.has(t));
+    log.info(`[claude/agent-api] Done: ${fullText.length} chars, tools=[${Array.from(usedTools).join(',')}], session=${sessionId || 'unknown'}`);
+    return { ok: true, response: fullText, sessionId, toolsUsed: Array.from(usedTools), usedFileTools };
+  } catch (err: any) {
+    if (abortController.signal.aborted) return { ok: false, error: 'Query timed out.', sessionId };
+    const detail = stderrBuf.trim();
+    const errMsg = detail ? `${err.message}\n\n${detail}` : err.message;
+    log.warn(`[claude/agent-api] Error: ${errMsg}`);
+    return { ok: false, error: errMsg, sessionId };
+  } finally {
+    clearTimeout(timeoutHandle);
+  }
+}

package/supervisor/harnesses/codex.ts

@@ -34,7 +34,7 @@ import { WORKSPACE_DIR } from '../../shared/paths.js';
 import type { SavedFile } from '../file-saver.js';
 import { getCodexAccessToken } from '../../worker/codex-auth.js';
 import { assembleSystemPrompt } from '../../worker/prompts/prompt-assembler.js';
-import type { OnAgentMessage, RecentMessage, AgentAttachment } from './types.js';
+import type { OnAgentMessage, RecentMessage, AgentAttachment, AgentQueryRequest, AgentQueryResult } from './types.js';
 export type { RecentMessage, AgentAttachment };
 
 /* ── Constants ─────────────────────────────────────────────────────────── */
@@ -170,6 +170,17 @@ class CodexRpc {
       log.warn(`[codex-rpc] malformed JSON from server: ${line.slice(0, 200)}`);
       return;
     }
+
+    // Server-initiated REQUEST (has both id AND method) — must reply or the
+    // server hangs forever. Approval requests get auto-accepted to match our
+    // bypass-permissions posture; anything else gets a method-not-found
+    // error reply so we never silently stall.
+    if (typeof msg.id === 'number' && typeof msg.method === 'string') {
+      this.handleServerRequest(msg);
+      return;
+    }
+
+    // RESPONSE to a request we sent.
     if (typeof msg.id === 'number') {
       const pending = this.pending.get(msg.id);
       if (!pending) return;
@@ -179,11 +190,36 @@ class CodexRpc {
       else pending.resolve(msg.result);
       return;
     }
+
+    // NOTIFICATION (no id).
     if (typeof msg.method === 'string') {
       this.notificationHandler({ method: msg.method, params: msg.params });
     }
   }
 
+  private handleServerRequest(msg: { id: number; method: string; params?: any }): void {
+    const isApproval = msg.method.endsWith('/requestApproval');
+    if (isApproval) {
+      log.info(`[codex-rpc] auto-accepting server request: ${msg.method}`);
+      this.respond(msg.id, 'acceptForSession');
+      return;
+    }
+    log.warn(`[codex-rpc] unhandled server request ${msg.method} — replying with error`);
+    this.respondError(msg.id, -32601, `Method ${msg.method} not implemented by Bloby client`);
+  }
+
+  private respond(id: number, result: any): void {
+    if (this.closed || !this.proc) return;
+    try { this.proc.stdin.write(JSON.stringify({ id, result }) + '\n'); }
+    catch (err: any) { log.warn(`[codex-rpc] respond failed: ${err.message}`); }
+  }
+
+  private respondError(id: number, code: number, message: string): void {
+    if (this.closed || !this.proc) return;
+    try { this.proc.stdin.write(JSON.stringify({ id, error: { code, message } }) + '\n'); }
+    catch (err: any) { log.warn(`[codex-rpc] respondError failed: ${err.message}`); }
+  }
+
   request<T = any>(method: string, params?: any, timeoutMs = REQUEST_TIMEOUT_MS): Promise<T> {
     if (this.closed || !this.proc) return Promise.reject(new Error('RPC connection closed'));
     const id = this.nextId++;
@@ -486,6 +522,11 @@ async function spawnAndInitialize(
       cwd: WORKSPACE_DIR,
       model: modelId,
       baseInstructions,
+      // Bloby's posture matches Claude's bypassPermissions — the bot is
+      // running on the user's own machine with their full consent. Skip the
+      // approval prompts and give it write access to the workspace + beyond.
+      approvalPolicy: 'never',
+      sandbox: 'danger-full-access',
     });
     conv.threadId = startResult.thread.id;
     conversations.set(conversationId, conv);
@@ -589,3 +630,147 @@ export async function startBlobyAgentQuery(
 export function stopBlobyAgentQuery(conversationId: string): void {
   endConversation(conversationId);
 }
+
+// ── Workspace agent endpoint (POST /api/agent/query) ──────────────────────
+
+/**
+ * One-shot Codex query that spawns its own short-lived app-server, runs a
+ * single turn, returns the accumulated response, and tears down. Mirrors
+ * what `agent-api.ts` previously did directly with the Claude SDK.
+ *
+ * `sessionId` carries a Codex `threadId` — when present we issue a
+ * `thread/resume` instead of `thread/start` to preserve server-side context.
+ */
+export async function runAgentQuery(req: AgentQueryRequest): Promise<AgentQueryResult> {
+  const token = await getCodexAccessToken();
+  if (!token) {
+    return { ok: false, error: 'Codex credentials not found or expired. Re-authenticate via the dashboard.' };
+  }
+
+  // Pull the active model + parse effort suffix from the user's config —
+  // agent-api callers don't get to pick.
+  let model = 'gpt-5.5';
+  let effort: string | undefined;
+  try {
+    const { loadConfig: loadCfg } = await import('../../shared/config.js');
+    const cfg = loadCfg();
+    if (cfg.ai?.model) {
+      const parsed = parseModelString(cfg.ai.model);
+      model = parsed.id;
+      effort = parsed.effort;
+    }
+  } catch {}
+
+  const timeout = Math.min(Math.max(req.timeout || 120_000, 5_000), 300_000);
+
+  const rpc = new CodexRpc();
+  rpc.start();
+
+  let fullText = '';
+  const usedTools = new Set<string>();
+  let usedFileTools = false;
+  let resolvedThreadId = req.sessionId || '';
+  let resolveTurn: (() => void) | null = null;
+  let turnError: string | null = null;
+  const turnDone = new Promise<void>((r) => { resolveTurn = r; });
+
+  rpc.onNotification((n) => {
+    const p = n.params || {};
+    switch (n.method) {
+      case 'item/agentMessage/delta': {
+        if (typeof p.delta === 'string') fullText += p.delta;
+        break;
+      }
+      case 'item/started': {
+        const item = p.item || {};
+        if (item.type === 'commandExecution') usedTools.add('shell');
+        else if (item.type === 'mcpToolCall') usedTools.add(item.toolName || item.name || 'mcp_tool');
+        else if (item.type === 'fileChange') { usedTools.add('file_change'); usedFileTools = true; }
+        else if (item.type === 'webSearch') usedTools.add('web_search');
+        break;
+      }
+      case 'item/completed': {
+        const item = p.item || {};
+        if (item.type === 'fileChange') usedFileTools = true;
+        if (item.type === 'agentMessage' && !fullText) {
+          const text = (item.content || []).map((c: any) => c.text || '').join('') || item.text || '';
+          if (text) fullText = text;
+        }
+        break;
+      }
+      case 'turn/completed': {
+        const status = p.turn?.status || 'completed';
+        if (status === 'failed' || status === 'systemError') {
+          turnError = p.turn?.error?.message || 'Codex turn failed.';
+        }
+        resolveTurn?.();
+        break;
+      }
+      case 'error': {
+        turnError = p.error?.message || 'Codex error';
+        resolveTurn?.();
+        break;
+      }
+    }
+  });
+
+  const timeoutHandle = setTimeout(() => {
+    if (!turnError) turnError = `Query timed out after ${timeout}ms.`;
+    resolveTurn?.();
+  }, timeout);
+
+  try {
+    log.info(`[codex/agent-api] Query: msg="${req.message.slice(0, 80)}..." model=${model} resume=${req.sessionId || 'none'}`);
+    await rpc.request('initialize', { clientInfo: CLIENT_INFO });
+    rpc.notify('initialized', {});
+
+    if (req.sessionId) {
+      // Resume an existing thread (if codex still has it). Caller must accept
+      // failure here — we fall back to a fresh thread.
+      try {
+        const r = await rpc.request<{ thread: { id: string } }>('thread/resume', { threadId: req.sessionId });
+        resolvedThreadId = r.thread.id;
+      } catch (err: any) {
+        log.warn(`[codex/agent-api] thread/resume failed (${err.message}); starting fresh thread`);
+        const r = await rpc.request<{ thread: { id: string } }>('thread/start', {
+          cwd: WORKSPACE_DIR,
+          model,
+          ...(req.systemPrompt ? { baseInstructions: req.systemPrompt } : {}),
+          approvalPolicy: 'never',
+          sandbox: 'danger-full-access',
+        });
+        resolvedThreadId = r.thread.id;
+      }
+    } else {
+      const r = await rpc.request<{ thread: { id: string } }>('thread/start', {
+        cwd: WORKSPACE_DIR,
+        model,
+        ...(req.systemPrompt ? { baseInstructions: req.systemPrompt } : {}),
+        approvalPolicy: 'never',
+        sandbox: 'danger-full-access',
+      });
+      resolvedThreadId = r.thread.id;
+    }
+
+    const turnParams: Record<string, any> = {
+      threadId: resolvedThreadId,
+      input: [{ type: 'text', text: req.message }],
+    };
+    if (effort) turnParams.effort = effort;
+    await rpc.request('turn/start', turnParams);
+
+    await turnDone;
+
+    if (turnError) {
+      return { ok: false, error: turnError, sessionId: resolvedThreadId, toolsUsed: Array.from(usedTools) };
+    }
+
+    log.info(`[codex/agent-api] Done: ${fullText.length} chars, tools=[${Array.from(usedTools).join(',')}], thread=${resolvedThreadId}`);
+    return { ok: true, response: fullText, sessionId: resolvedThreadId, toolsUsed: Array.from(usedTools), usedFileTools };
+  } catch (err: any) {
+    return { ok: false, error: err?.message || String(err), sessionId: resolvedThreadId };
+  } finally {
+    clearTimeout(timeoutHandle);
+    rpc.close();
+  }
+}

package/supervisor/harnesses/types.ts

@@ -78,4 +78,29 @@ export interface Harness {
   ): Promise<void>;
 
   stopBlobyAgentQuery(conversationId: string): void;
+
+  /* ── Workspace agent endpoint (POST /api/agent/query) ── */
+  runAgentQuery(req: AgentQueryRequest): Promise<AgentQueryResult>;
+}
+
+export interface AgentQueryRequest {
+  message: string;
+  /** Already-resolved system prompt content (not a path). Empty/omitted → use the harness's default coding-agent prompt. */
+  systemPrompt?: string;
+  /** Provider-specific session id to resume (Claude: SDK session_id; Codex: threadId). */
+  sessionId?: string;
+  /** Max turns (Claude only — Codex has no equivalent). */
+  maxTurns?: number;
+  /** Hard timeout in ms. */
+  timeout?: number;
+}
+
+export interface AgentQueryResult {
+  ok: boolean;
+  response?: string;
+  /** Provider-specific session id the caller can pass back to resume this conversation. */
+  sessionId?: string;
+  toolsUsed?: string[];
+  usedFileTools?: boolean;
+  error?: string;
 }