AGENTS.md

1# src/tools/look-at/ -- Image and PDF Analysis Tool
2 
3**Generated:** 2026-05-18
4 
5## OVERVIEW
6 
714 files. The `look_at` tool delegates image, PDF, and diagram analysis to the `multimodal-looker` subagent. Conditional gate: tool is only registered when `multimodal-looker` is not in `disabled_agents`. Default subagent route: GPT-5.6 Sol at low effort through OpenAI, OpenCode, or Vercel. This is a summary extractor, not a precise reader.
8 
9## EXECUTION FLOW
10 
111. **Args** (`look-at-arguments.ts`) -- normalize `file_path`/`image_data` aliases, validate one-of requirement, reject remote URLs
122. **Prep** (`look-at-input-preparer.ts`) -- resolve path, detect MIME from extension or Base64 header, convert unsupported images to JPEG
133. **Spawn** (`look-at-session-runner.ts`) -- create child session with `multimodal-looker` agent, attach file as message part, disable `task`/`call_omo_agent`/`look_at` to prevent recursion
144. **Poll** (`session-poller.ts`) -- wait until idle (1s interval, 120s timeout)
155. **Extract** (`assistant-message-extractor.ts`) -- pull latest assistant text from session messages
166. **Return** -- summary text back to caller
17 
18## FILE CATALOG
19 
20| File | Responsibility |
21|------|----------------|
22| `tools.ts` | `createLookAt()` factory -- tool schema + entry point |
23| `look-at-arguments.ts` | Zod arg schema, normalize aliases, validate inputs |
24| `look-at-input-preparer.ts` | Build `LookAtFilePart` from path or base64; trigger conversion if needed |
25| `look-at-prompt.ts` | System prompt for the multimodal session |
26| `look-at-session-runner.ts` | Orchestrate child session creation, prompt dispatch, message fetch |
27| `session-poller.ts` | Poll session status until idle |
28| `assistant-message-extractor.ts` | Extract latest assistant text from raw session messages |
29| `image-converter.ts` | Convert HEIC/WebP/RAW/PSD to JPEG via sips or ImageMagick |
30| `mime-type-inference.ts` | Detect MIME from file extension or Base64 header |
31| `missing-file-error.ts` | Clear `ENOENT` error message when file is missing |
32| `multimodal-agent-metadata.ts` | Resolve actual model for multimodal-looker from config or dynamic pipeline |
33| `multimodal-fallback-chain.ts` | Build vision-capable fallback chain: GPT-5.6 Sol, Kimi K3, GLM-4.6V, GPT-5 Nano |
34| `constants.ts` | `MULTIMODAL_LOOKER_AGENT`, `LOOK_AT_DESCRIPTION` |
35| `types.ts` | `LookAtArgs` interface |
36 
37## GATE
38 
39Conditional. Tool is registered only when `multimodal-looker` is absent from `disabled_agents`.
40 
41## USE CASE
42 
43PDFs, screenshots, diagrams -- quick summary extraction. NOT for visual precision, aesthetic evaluation, or exact accuracy. Use the Read tool for those cases instead.
44 
45## DISTINCTION
46 
47This is the TOOL that DELEGATES TO the `multimodal-looker` AGENT. The agent lives in `src/agents/builtin-agents/multimodal-looker.ts`; this tool is the invocation harness.
48 
49## NOTES
50 
51- Temporary converted images are cleaned up in `finally` blocks
52- The subagent has `read` tool disabled by default (`READ_ENABLED = false`); the file is passed as an attachment
53